◆ Agenti Locali — Agenti che agiscono sul tuo computer, senza cloud · 24 € · o tutti i kit 49 € →

#OpenClaw e Ollama: chi fa cosa

OpenClaw è un gateway: un processo che riceve i vostri messaggi da un servizio di messaggistica, li trasmette a un modello linguistico ed esegue le azioni richieste da quel modello. Ollama è un server di modelli: carica un modello in memoria e risponde sulla porta 11434 della macchina, all'indirizzo http://localhost:11434 per impostazione predefinita. Collegare l'uno all'altro significa dichiarare Ollama come provider in OpenClaw, quindi designare un modello locale come modello principale dell'agente.

Secondo la documentazione di OpenClaw, questo collegamento passa dall'API nativa di Ollama (l'endpoint /api/chat), che supporta la risposta in streaming e la chiamata agli strumenti. Questo dettaglio conta più di quanto sembri: vedremo che un indirizzo scritto male basta a far passare il gateway a un'altra modalità, nella quale gli strumenti non funzionano più.

Ollama: Carica il modello, gli assegna una finestra di contesto e genera il testo. È lui a decidere quanta memoria viene consumata.
OpenClaw: Invia a ogni turno la consegna di sistema, la descrizione degli strumenti disponibili e la cronologia della conversazione, poi esegue gli strumenti richiesti dal modello.
Il modello: Deve tenere a mente una consegna lunga e saper chiedere uno strumento nel formato previsto. Non tutti i modelli locali sono in grado di farlo.
Cosa non cambia: I servizi di messaggistica, la memoria dell'assistente, il token e la sicurezza del gateway restano configurati sul lato OpenClaw, indipendentemente dal provider del modello.

Questo collegamento è più delicato di quello di un'interfaccia di conversazione. Una chat invia alcune righe al modello; un agente gli invia subito diverse migliaia di token di consegne e definizioni degli strumenti, ancora prima del tuo primo messaggio. Le impostazioni predefinite di Ollama sono pensate per il primo caso, non per il secondo.

Locale non significa privo di rischi

Un modello locale evita di inviare le tue conversazioni a un provider online. Non elimina nessuno dei rischi propri di un agente: OpenClaw legge contenuti provenienti dall'esterno e può eseguire comandi. In genere un modello piccolo si lascia sviare più facilmente da un testo malevolo rispetto a uno grande, e la documentazione sulla sicurezza del progetto invita alla prudenza su questo punto. Mantieni il gateway su una macchina dedicata, con il minor numero possibile di strumenti, e riesegui openclaw security audit --deep dopo aver cambiato modello.

#Prerequisiti

Il kit Agenti Locali

Agenti che agiscono sulla tua macchina: Cline agentico, MCP, n8n + Ollama, automazioni locali.

Spazio online a vita
PDF + file
Aggiornamenti a vita

Il kit Agenti Locali →o tutti i kit a vita — 49 € →

OpenClaw installato: Un gateway che si avvia e la cui diagnostica ha esito positivo. L'installazione non viene trattata qui: consultate la nostra guida «Installare OpenClaw con Docker».
Ollama installato e aggiornato: Il comando ollama launch usato più avanti esiste solo nelle versioni recenti. L'installazione è trattata nella nostra guida «Installare Ollama».
Memoria per il modello e il suo contesto: Riferimenti in Q4_K_M per i soli pesi: circa 5 GB per un modello da 7 miliardi di parametri, 9 GB per 14 miliardi, 19 GB per 32 miliardi. La finestra di contesto richiesta da un agente si aggiunge a questa cifra.
Accesso al terminale: Sulla macchina che ospita il gateway e su quella che ospita Ollama se non è la stessa.

Terminale — verificare i due strumenti

ollama --version
openclaw --version

# Le serveur Ollama répond-il ?
curl http://localhost:11434/api/tags

L'ultimo comando deve restituire l'elenco dei modelli installati, in formato JSON. Una connessione rifiutata significa che Ollama non è avviato: avviate l'applicazione oppure ollama serve in un terminale. È inutile procedere finché questa risposta non arriva.

#Passaggio 1: prevedere 64 000 token di contesto

È l'impostazione che fa fallire il maggior numero di installazioni e viene configurata sul lato Ollama, non sul lato OpenClaw. La pagina che Ollama dedica a OpenClaw indica che l'assistente ha bisogno di una grande finestra di contesto e raccomanda almeno 64 000 token con un modello locale. La sua pagina sulla lunghezza del contesto indica lo stesso valore per gli agenti, la ricerca web e gli strumenti di codice.

Invece Ollama sceglie la propria finestra predefinita in base alla memoria video disponibile: secondo la stessa documentazione, circa 4 000 token sotto i 24 GiB di VRAM, 32 000 tra 24 e 48 GiB, 256 000 a partire da 48 GiB. Su una scheda da 12 o 16 GB, il server si avvia quindi con una finestra sedici volte più piccola rispetto alla raccomandazione. Nulla lo segnala: Ollama tronca ciò che eccede, senza messaggi di errore.

Terminale — Ollama avviato manualmente (Linux, macOS)

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Se Ollama funziona già come applicazione (macOS, Windows), non eseguire questo comando: un secondo server entrerebbe in conflitto sulla porta 11434. Imposta la lunghezza del contesto nelle impostazioni dell'applicazione. Su Linux, quando Ollama è stato installato come servizio systemd, la variabile va dichiarata nel servizio stesso.

Terminale — Ollama installato come servizio (Linux)

sudo systemctl edit ollama.service

# Dans l'éditeur qui s'ouvre, ajouter ces deux lignes :
# [Service]
# Environment="OLLAMA_CONTEXT_LENGTH=64000"

sudo systemctl daemon-reload
sudo systemctl restart ollama

64 000 token si pagano in memoria

La finestra di contesto riserva memoria oltre a quella occupata dai pesi del modello. Un modello che regge agevolmente una conversazione può trasferire parte del carico al processore una volta aumentato il contesto, e l'agente diventa allora molto lento. Non forniamo un numero, perché dipende dal modello: il comando ollama ps, illustrato al passaggio 4, mostra ciò che viene realmente allocato. Se si verifica un eccesso, scegliete un modello più piccolo invece di ridurre il contesto. Due variabili documentate nelle FAQ di Ollama riducono il consumo: OLLAMA_FLASH_ATTENTION=1 e OLLAMA_KV_CACHE_TYPE=q8_0.

#Passaggio 2: scegliere un modello in grado di chiamare gli strumenti

Un agente agisce soltanto tramite i suoi strumenti: leggere un file, eseguire un comando, cercare sul web. Un modello che non sa formulare una richiesta allo strumento risponderà educatamente ai tuoi messaggi, ma non farà mai nulla. Questa pagina non classifica i modelli; fornisce i criteri da verificare prima di collegarne uno.

La capacità «tools»: Il comando ollama show affiche include una sezione Capabilities. Deve contenere tools. Nella libreria di Ollama, il filtro corrispondente si trova all'indirizzo https://ollama.com/search?c=tools.
Una finestra nativa sufficiente: Lo stesso comando visualizza la lunghezza massima del contesto del modello. Un modello progettato per 8 000 o 32 000 token non potrà seguire la raccomandazione di 64 000, indipendentemente dall'impostazione del server.
Un budget di memoria realistico: Pesi e contesto devono stare insieme nella VRAM o nella memoria unificata di un Mac. Su una scheda da 12 GB (RTX 3060, RTX 4070), questo orienta verso modelli nettamente più piccoli di quelli che la scheda accetta in una semplice conversazione; 16 GB (RTX 4080) e 24 GB (RTX 4090) lasciano più margine.
La tenuta nel tempo: Un agente concatena diverse chiamate agli strumenti per ogni richiesta. I modelli molto piccoli sbagliano più spesso formato o strumento. Nessuna scheda sostituisce una prova con le tue richieste, iniziando da quelle a basso rischio.

Terminale — scaricare e poi ispezionare un modello

ollama pull gpt-oss:20b
ollama show gpt-oss:20b

Il nome gpt-oss:20b serve da esempio nel seguito di questa guida: sostituitelo con il modello che avete scelto. La pagina di integrazione di Ollama mantiene aggiornata una lista di modelli suggeriti per OpenClaw, che cambia con il susseguirsi delle uscite; è meglio consultarla piuttosto che affidarsi a un elenco statico qui.

Un modello «cloud» non è un modello locale

La libreria di Ollama e il selettore del comando ollama launch propongono anche modelli la cui etichetta termina con cloud. Vengono eseguiti sui server di Ollama, non sulla vostra macchina: i vostri messaggi escono dal vostro ambiente. Per un'installazione realmente locale, scegliete un modello scaricato, visibile in ollama list.

#Passaggio 3: configurare il provider Ollama in OpenClaw

Esistono due strade. La prima è un comando di Ollama che scrive la configurazione al posto vostro. La seconda consiste nel dichiarare personalmente il provider nella configurazione di OpenClaw; è indispensabile non appena il gateway viene eseguito in Docker o Ollama si trova su un'altra macchina.

#Percorso rapido: ollama launch openclaw

Terminale

# Configurer OpenClaw pour Ollama et démarrer la passerelle
ollama launch openclaw

# Configurer sans rien lancer
ollama launch openclaw --config

Secondo la documentazione di Ollama, questo comando fa scegliere un modello, configura OpenClaw per usare Ollama e avvia il gateway; se è già in esecuzione, ricarica autonomamente la nuova configurazione. Il vecchio nome del progetto resta accettato: ollama launch clawdbot è un alias. Il comando è destinato a un OpenClaw installato direttamente sulla macchina, con il comando openclaw disponibile nel terminale. Non sostituisce il passaggio 1: la stessa pagina chiede di rilevare il contesto del server.

#Via manuale: dichiarare autonomamente il provider

La documentazione di OpenClaw descrive innanzitutto una modalità di rilevamento automatico. Forniamo una chiave fittizia, poiché Ollama non ne richiede alcuna, e OpenClaw interroga l'istanza locale all'indirizzo http://127.0.0.1:11434 per trovare i modelli installati.

Terminale — attivare il fornitore e scegliere il modello

# N'importe quelle valeur convient : Ollama ne vérifie pas de clé
export OLLAMA_API_KEY="ollama-local"

# Ou l'inscrire dans la configuration d'OpenClaw
openclaw config set models.providers.ollama.apiKey "ollama-local"

# Lister les modèles vus par OpenClaw, puis fixer le modèle principal
openclaw models list
openclaw models set ollama/gpt-oss:20b

Un modello viene indicato nella forma ollama/ seguita dal nome esatto visualizzato da ollama list, etichetta compresa. Quando il gateway funziona come servizio, preferisci la registrazione nella configurazione alla variabile d'ambiente: una variabile esportata nel tuo terminale non viene trasmessa a un processo avviato dal sistema. Con un'installazione Docker, anteponi docker compose run --rm openclaw-cli a ogni comando openclaw.

La seconda modalità è la dichiarazione esplicita, nel file ~/.openclaw/openclaw.json, scritto in JSON5. Serve quando Ollama funziona altrove rispetto alla macchina del gateway, quando un modello non compare nell'elenco o quando vuoi impostare tu la finestra dichiarata all'agente.

~/.openclaw/openclaw.json — dichiarazione esplicita (JSON5)

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        models: [
          {
            id: "gpt-oss:20b",
            name: "GPT-OSS 20B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 64000,
            maxTokens: 8192
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: { primary: "ollama/gpt-oss:20b" }
    }
  }
}

baseUrl: L'indirizzo del server Ollama, porta compresa, senza altro dopo. È l'unica riga da modificare quando Ollama funziona su un'altra macchina.
api: "ollama": Richiede esplicitamente l'API nativa di Ollama, quella che gestisce la chiamata agli strumenti.
apiKey: Un valore fittizio. Serve soltanto ad attivare il provider.
contextWindow: La finestra dichiarata a OpenClaw, che la usa per gestire la lunghezza della cronologia. Deve corrispondere a ciò che Ollama carica realmente, non a ciò che il modello accetterebbe in teoria.
maxTokens: Il limite massimo della lunghezza di una risposta.
cost: Niente costi: un modello locale non viene fatturato a token.
agents.defaults.model.primary: Il modello usato per impostazione predefinita dall'agente, nella forma ollama/nome-del-modello.

Questo esempio riprende la struttura fornita dalla documentazione di OpenClaw; i valori di contextWindow e maxTokens sono nostri, da adattare al vostro modello. Due cose da ricordare. Innanzitutto, impostate reasoning su true per un modello di ragionamento. Inoltre, secondo la stessa documentazione, il rilevamento automatico è disabilitato non appena esiste una voce esplicita models.providers.ollama: ogni modello che volete usare deve quindi figurare nell'elenco models.

Niente /v1 alla fine dell'indirizzo

Molti strumenti si collegano a Ollama tramite la sua interfaccia compatibile con OpenAI, all'indirizzo http://localhost:11434/v1. La documentazione di OpenClaw chiede esplicitamente di non usarla: in questa modalità, la chiamata agli strumenti non è più affidabile e il modello può restituire il JSON dello strumento come testo semplice. L'indirizzo corretto si ferma alla porta: http://localhost:11434.

Terminale — applicare e controllare

openclaw gateway restart
openclaw doctor

#Gateway in Docker o Ollama su un'altra macchina

All'interno di un contenitore, localhost indica il contenitore stesso. Un gateway OpenClaw avviato con Docker non vede quindi Ollama della macchina host all'indirizzo http://localhost:11434: la connessione viene rifiutata anche se dal vostro terminale funziona tutto. La soluzione dipende da dove viene eseguito Ollama.

Docker Desktop (macOS, Windows): Il nome host.docker.internal indica la macchina host dal container. Indicate http://host.docker.internal:11434 come baseUrl nella dichiarazione esplicita.
Docker Engine su Linux: Questo nome non esiste per impostazione predefinita: bisogna aggiungerlo al servizio con extra_hosts, come mostrato di seguito. Inoltre, Ollama deve essere in ascolto su un'interfaccia raggiungibile dal contenitore, cosa che non avviene con l'impostazione originale, limitata al loopback.
Ollama su un'altra macchina: Inserite in baseUrl l'indirizzo di questa macchina sulla vostra rete locale o sulla vostra VPN, e configurate allo stesso modo l'ascolto di Ollama su questa macchina.

docker-compose.override.yml — esempio da adattare (Linux)

services:
  openclaw-gateway:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Terminale — far ascoltare Ollama oltre il loopback (servizio Linux)

sudo systemctl edit ollama.service

# Dans l'éditeur qui s'ouvre, ajouter ces deux lignes :
# [Service]
# Environment="OLLAMA_HOST=0.0.0.0:11434"

sudo systemctl daemon-reload
sudo systemctl restart ollama

Il file Compose è un esempio da parte nostra, non un estratto della documentazione di OpenClaw: confronta il nome del servizio con il docker-compose.yml della tua versione. La variabile OLLAMA_HOST, invece, è descritta nelle FAQ di Ollama. Valuta le sue implicazioni: con 0.0.0.0, il server ascolta su tutte le interfacce della macchina e l'API di Ollama non richiede alcuna autenticazione. Un firewall deve limitare la porta 11434 alla rete Docker o alla rete locale, e questa porta non deve mai essere raggiungibile da Internet. La nostra guida alla messa in sicurezza di un server Ollama illustra queste regole.

#Passaggio 4: verificare il collegamento end-to-end

Un agente che risponde «ciao» non dimostra nulla: questa risposta non richiede né strumenti né contesto. La verifica utile procede strato dopo strato, dal server dei modelli fino alla messaggistica.

01
Testare la chiamata agli strumenti usando solo Ollama
Inviate al server una domanda accompagnata da uno strumento fittizio, usando il comando qui sotto. La risposta deve contenere un campo tool_calls che nomina lo strumento e gli passa un argomento. Se il modello risponde con una frase, non è adatto a un agente.
02
Controllare cosa vede OpenClaw
Il comando openclaw models list deve mostrare il vostro modello nella forma ollama/nome-del-modello, e openclaw doctor non deve segnalare errori del fornitore.
03
Chiedere un'azione, non una risposta
Dall'interfaccia di controllo o dalla vostra messaggistica, inviate una richiesta che obblighi l'agente a usare uno strumento, per esempio elencare i file del suo spazio di lavoro. Deve farlo davvero, non descrivere ciò che farebbe.
04
Guardare cosa ha caricato Ollama
Subito dopo questo scambio, eseguite ollama ps sulla macchina del server e leggete le colonne CONTEXT e PROCESSOR.

Terminale — 1. una chiamata agli strumenti direttamente su Ollama

curl http://localhost:11434/api/chat -d '{
  "model": "gpt-oss:20b",
  "stream": false,
  "messages": [{"role": "user", "content": "Quel temps fait-il à Lyon ?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Donne la météo actuelle pour une ville",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}'

Terminale — 2 e 4. lato OpenClaw, poi lato Ollama

openclaw models list
openclaw doctor

# Après un échange avec l'agent
ollama ps

Nell'output di ollama ps, la colonna CONTEXT indica la finestra effettivamente allocata al modello caricato. Se visualizza 4096 mentre puntavi a 64 000, l'impostazione del passaggio 1 non è stata applicata, qualunque cosa indichi la configurazione di OpenClaw. La colonna PROCESSOR indica la ripartizione tra scheda grafica e processore: la dicitura 100% GPU è quella che cerchiamo; una ripartizione mista segnala che il modello e il suo contesto superano la memoria video.

→

Isolare il livello difettoso

Se il test diretto su Ollama (il primo dei quattro controlli) fallisce, il problema riguarda il modello o Ollama e nessuna impostazione di OpenClaw potrà risolverlo. Se ha esito positivo ma l'agente non agisce, cercate il problema nel collegamento: indirizzo del server, modalità API, finestra di contesto. Questa selezione evita di modificare la configurazione a caso.

#Guasti silenziosi: sintomi e cause

Gli errori evidenti (connessione rifiutata, modello introvabile) si leggono nei log. I guasti qui sotto sono più costosi, perché l'assistente continua a rispondere: risponde soltanto male.

L'assistente ignora le sue istruzioni o risponde fuori tema: Causa più probabile: il contesto è troncato. La consegna di sistema e le definizioni degli strumenti superano la finestra caricata da Ollama, che ne elimina una parte senza avvisare. Controlla la colonna CONTEXT di ollama ps e riprendi il passaggio 1.
Al posto dell'azione viene visualizzato del JSON: Il modello ha formulato correttamente una chiamata allo strumento, ma il gateway l'ha ricevuta come testo. È il segno di un indirizzo con /v1 o di un fornitore dichiarato in modalità compatibile con OpenAI. Tornate all'indirizzo nativo e ad api: "ollama".
Descrive ciò che farebbe, senza fare nulla: Il modello non dichiara la capacità tools, oppure è troppo limitato per usarla nel mezzo di una consegna lunga. Ripetete il test diretto su Ollama descritto al passaggio 4; se fallisce, cambiate modello.
Il modello non compare in openclaw models list: Tre possibilità. Il provider non è attivato (manca la chiave fittizia oppure la variabile non viene trasmessa al servizio). Esiste una voce esplicita models.providers.ollama che non elenca questo modello. Oppure il modello non dichiara la chiamata agli strumenti: secondo la documentazione che conosciamo, la scoperta automatica considera solo quelli che la dichiarano, un comportamento che potrebbe essere cambiato a seconda delle versioni.
La regolazione del contesto resta senza effetto: La variabile OLLAMA_CONTEXT_LENGTH è stata esportata in un terminale mentre Ollama era in esecuzione come servizio o applicazione: il server non l'ha mai vista. Dichiaratela nel servizio o nelle impostazioni dell'applicazione, quindi riavviate Ollama.
Le risposte richiedono molto tempo oppure non arrivano: O il modello trabocca sul processore (colonna PROCESSOR di ollama ps), oppure è stato scaricato dopo un periodo di inattività e viene ricaricato a ogni messaggio: per impostazione predefinita, Ollama mantiene un modello in memoria per cinque minuti. La variabile OLLAMA_KEEP_ALIVE prolunga questo intervallo.
Tutto funziona nel terminale, nulla dal gateway: Il gateway viene eseguito in un container e cerca Ollama sul proprio localhost. Consultate la sezione su Docker.
«Model context window too small»: Questa non è silenziosa, ma è fuorviante: le versioni di OpenClaw che conosciamo rifiutano un modello la cui finestra dichiarata è troppo piccola. Controllate contextWindow nella dichiarazione esplicita e, di conseguenza, il contesto di Ollama.

Terminale — seguire i log di entrambi i lati

# Passerelle OpenClaw
openclaw logs --follow

# Serveur Ollama installé comme service (Linux)
journalctl -u ollama -f

Un limite da tenere presente una volta stabilito il collegamento: un modello locale collegato correttamente non si comporterà necessariamente come un grande modello online nelle attività lunghe o ambigue. Qui non pubblichiamo alcun confronto né alcuna velocità di elaborazione. Iniziate con richieste semplici e prive di conseguenze, osservate dove il modello cede e mantenete un provider online come modello di riserva se l'assistente vi serve quotidianamente.

#Fonti ufficiali da tenere a portata di mano

Questa guida non si basa su alcun test interno: non contiene né durata, né velocità, né punteggio. I comandi e i nomi dei campi riprendono la documentazione dei due progetti, che cambia da una versione all'altra: opzioni di ollama launch, comportamento del rilevamento automatico, valori predefiniti. In caso di discrepanza tra questa pagina e la documentazione, fa fede la documentazione.

Ollama: integrazione OpenClaw

https://docs.ollama.com/integrations/openclaw

OpenClaw: provider Ollama

https://docs.openclaw.ai/providers/ollama

Ollama : lunghezza del contesto

https://docs.ollama.com/context-length

Ollama: FAQ (variabili del server)

https://docs.ollama.com/faq

OpenClaw: sicurezza del gateway

https://docs.openclaw.ai/gateway/security

#Per approfondire

Il collegamento si basa su tre concetti trattati in dettaglio altrove sul sito: il server Ollama, la finestra di contesto e la chiamata agli strumenti.

Installare Ollama: L'installazione del server di modelli, le sue impostazioni di base e ciò che può uscire dalla macchina. https://quelllm.fr/guide/installer-ollama
Comprendere la finestra di contesto: Che cosa misura un token, perché il contesto consuma memoria e come dimensionarlo. https://quelllm.fr/guide/comprendre-fenetre-contexte
La chiamata agli strumenti con Ollama: Il formato delle richieste agli strumenti e il modo di testarle al di fuori di qualsiasi agente. https://quelllm.fr/guide/appel-outil-ollama-tutoriel
Hermes Agent con Ollama: Un altro agente self-hosted collegato a un modello locale, per confrontare gli approcci. https://quelllm.fr/guide/hermes-agent-ollama-guide
Installare OpenClaw con Docker: L'installazione del gateway, il suo aggiornamento e le regole di esposizione su un VPS. https://quelllm.fr/guide/installer-openclaw-docker

Questa guida ti è stata utile?

Un feedback, un errore, una precisazione? Facci sapere, così la guida migliora per tutti.

I kit QuelLLMLa guida di riferimento per ogni uso

Agenti Locali Copilota Locale IA locale RAG Locale IA in Azienda IA Senza Filtri Mac Immagini IA

Tutti i kit a vita — 49 €