Vai al contenuto principale
OpenClaw si integra con l’API nativa di Ollama (/api/chat) per modelli cloud ospitati e server Ollama locali/self-hosted. Puoi usare Ollama in tre modalità: Cloud + Local tramite un host Ollama raggiungibile, Cloud only verso https://ollama.com oppure Local only verso un host Ollama raggiungibile. OpenClaw registra anche ollama-cloud come id provider ospitato di prima classe per l’uso diretto di Ollama Cloud. Usa ref come ollama-cloud/kimi-k2.5:cloud quando vuoi il routing solo cloud senza condividere l’id provider locale ollama. Per la pagina di configurazione dedicata solo cloud, consulta Ollama Cloud.
Utenti Ollama remoti: non usare l’URL compatibile con OpenAI /v1 (http://host:11434/v1) con OpenClaw. Questo interrompe le chiamate agli strumenti e i modelli potrebbero produrre JSON grezzo degli strumenti come testo normale. Usa invece l’URL dell’API nativa di Ollama: baseUrl: "http://host:11434" (senza /v1).
La configurazione del provider Ollama usa baseUrl come chiave canonica. OpenClaw accetta anche baseURL per compatibilità con esempi in stile SDK OpenAI, ma la nuova configurazione dovrebbe preferire baseUrl.

​
Regole di autenticazione

Gli host Ollama locali e LAN non richiedono un vero token bearer. OpenClaw usa il marcatore locale ollama-local solo per URL di base Ollama loopback, di rete privata, .local e hostname semplici.
Gli host pubblici remoti e Ollama Cloud (https://ollama.com) richiedono una credenziale reale tramite OLLAMA_API_KEY, un profilo di autenticazione o apiKey del provider. Per l’uso ospitato diretto, preferisci il provider ollama-cloud.
Gli id provider personalizzati che impostano api: "ollama" seguono le stesse regole. Per esempio, un provider ollama-remote che punta a un host Ollama su una LAN privata può usare apiKey: "ollama-local" e i sotto-agenti risolveranno quel marcatore tramite l’hook del provider Ollama invece di trattarlo come una credenziale mancante. La ricerca in memoria può anche impostare agents.defaults.memorySearch.provider su quell’id provider personalizzato, così gli embedding usano l’endpoint Ollama corrispondente.
auth-profiles.json archivia la credenziale per un id provider. Inserisci le impostazioni dell’endpoint (baseUrl, api, id modello, header, timeout) in models.providers.<id>. I vecchi file di profili di autenticazione piatti, come { "ollama-windows": { "apiKey": "ollama-local" } }, non sono un formato runtime; esegui openclaw doctor --fix per riscriverli nel profilo canonico di chiave API ollama-windows:default con un backup. baseUrl in quel file è rumore di compatibilità e dovrebbe essere spostato nella configurazione del provider.
Quando Ollama viene usato per gli embedding di memoria, l’autenticazione bearer è limitata all’host in cui è stata dichiarata:
  • Una chiave a livello di provider viene inviata solo all’host Ollama di quel provider.
  • agents.*.memorySearch.remote.apiKey viene inviata solo al relativo host remoto di embedding.
  • Un valore env puro OLLAMA_API_KEY viene trattato come convenzione di Ollama Cloud, non inviato di default a host locali o self-hosted.

​
Primi passi

Scegli il metodo e la modalità di configurazione che preferisci.
Ideale per: il percorso più rapido verso una configurazione Ollama cloud o locale funzionante.
1

Esegui l'onboarding

openclaw onboard
Seleziona Ollama dall’elenco dei provider.
2

Scegli la modalità

  • Cloud + Local — host Ollama locale più modelli cloud instradati tramite quell’host
  • Cloud only — modelli Ollama ospitati tramite https://ollama.com
  • Local only — solo modelli locali
3

Seleziona un modello

Cloud only richiede OLLAMA_API_KEY e suggerisce default cloud ospitati. Cloud + Local e Local only chiedono un URL di base Ollama, rilevano i modelli disponibili ed eseguono automaticamente il pull del modello locale selezionato se non è ancora disponibile. Quando Ollama segnala un tag :latest installato, come gemma4:latest, la configurazione mostra quel modello installato una sola volta invece di mostrare sia gemma4 sia gemma4:latest o di eseguire di nuovo il pull dell’alias semplice. Cloud + Local verifica anche se quell’host Ollama ha effettuato l’accesso per l’accesso cloud.
4

Verifica che il modello sia disponibile

openclaw models list --provider ollama

​
Modalità non interattiva

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk
Facoltativamente, specifica un URL di base o modello personalizzato:
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

​
Modelli cloud

Cloud + Local usa un host Ollama raggiungibile come punto di controllo sia per i modelli locali sia per quelli cloud. Questo è il flusso ibrido preferito di Ollama.Usa Cloud + Local durante la configurazione. OpenClaw richiede l’URL di base Ollama, rileva i modelli locali da quell’host e verifica se l’host ha effettuato l’accesso per l’accesso cloud con ollama signin. Quando l’host ha effettuato l’accesso, OpenClaw suggerisce anche default cloud ospitati come kimi-k2.5:cloud, minimax-m2.7:cloud e glm-5.1:cloud.Se l’host non ha ancora effettuato l’accesso, OpenClaw mantiene la configurazione solo locale finché non esegui ollama signin.

​
Rilevamento dei modelli (provider implicito)

Quando imposti OLLAMA_API_KEY (o un profilo di autenticazione) e non definisci models.providers.ollama o un altro provider remoto personalizzato con api: "ollama", OpenClaw rileva i modelli dall’istanza Ollama locale all’indirizzo http://127.0.0.1:11434.
ComportamentoDettaglio
Query del catalogoInterroga /api/tags
Rilevamento capacitàUsa lookup best-effort /api/show per leggere contextWindow, parametri Modelfile num_ctx espansi e capacità incluse vision/tools
Modelli visionI modelli con una capacità vision riportata da /api/show sono contrassegnati come compatibili con immagini (input: ["text", "image"]), quindi OpenClaw inserisce automaticamente le immagini nel prompt
Rilevamento ragionamentoUsa le capacità di /api/show quando disponibili, incluso thinking; ripiega su un’euristica basata sul nome del modello (r1, reasoning, think) quando Ollama omette le capacità
Limiti di tokenImposta maxTokens al limite massimo di token Ollama predefinito usato da OpenClaw
CostiImposta tutti i costi a 0
Questo evita voci modello manuali mantenendo il catalogo allineato con l’istanza Ollama locale. Puoi usare un ref completo come ollama/<pulled-model>:latest in infer model run locale; OpenClaw risolve quel modello installato dal catalogo live di Ollama senza richiedere una voce models.json scritta a mano. Per gli host Ollama con accesso effettuato, alcuni modelli :cloud possono essere utilizzabili tramite /api/chat e /api/show prima che compaiano in /api/tags. Quando selezioni esplicitamente un ref completo ollama/<model>:cloud, OpenClaw valida quel modello mancante esatto con /api/show e lo aggiunge al catalogo runtime solo se Ollama conferma i metadati del modello. Gli errori di battitura continuano a fallire come modelli sconosciuti invece di essere creati automaticamente. 
# See what models are available
ollama list
openclaw models list
Per uno smoke test ristretto di generazione testo che evita l’intera superficie strumenti dell’agente, usa infer model run locale con un ref completo di modello Ollama: 
OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/llama3.2:latest \
    --prompt "Reply with exactly: pong" \
    --json
Quel percorso usa comunque il provider configurato di OpenClaw, l’autenticazione e il trasporto nativo Ollama, ma non avvia un turno di agente chat né carica contesto MCP/strumenti. Se questo riesce mentre le normali risposte dell’agente falliscono, risolvi poi i problemi della capacità del modello per prompt/strumenti dell’agente. Per uno smoke test ristretto di modello vision sullo stesso percorso snello, aggiungi uno o più file immagine a infer model run. Questo invia il prompt e l’immagine direttamente al modello vision Ollama selezionato senza caricare strumenti chat, memoria o contesto di sessione precedente: 
OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/qwen2.5vl:7b \
    --prompt "Describe this image in one sentence." \
    --file ./photo.jpg \
    --json
model run --file accetta file rilevati come image/*, inclusi input PNG, JPEG e WebP comuni. I file non immagine vengono rifiutati prima che Ollama sia chiamato. Per il riconoscimento vocale, usa invece openclaw infer audio transcribe. Quando passi una conversazione a /model ollama/<model>, OpenClaw lo tratta come una selezione utente esatta. Se l’baseUrl Ollama configurato non è raggiungibile, la risposta successiva fallisce con l’errore del provider invece di rispondere silenziosamente da un altro modello di fallback configurato. I processi cron isolati eseguono un controllo di sicurezza locale aggiuntivo prima di avviare il turno dell’agente. Se il modello selezionato si risolve in un provider Ollama locale, di rete privata o .local e /api/tags non è raggiungibile, OpenClaw registra quell’esecuzione cron come skipped con l’ollama/<model> selezionato nel testo dell’errore. Il preflight dell’endpoint viene memorizzato nella cache per 5 minuti, quindi più processi cron puntati allo stesso daemon Ollama arrestato non avviano tutti richieste di modello destinate a fallire. Verifica dal vivo il percorso di testo locale, il percorso di stream nativo e gli embedding rispetto a Ollama locale con: 
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
  pnpm test:live -- extensions/ollama/ollama.live.test.ts
Per gli smoke test con chiave API di Ollama Cloud, punta il test live a https://ollama.com e scegli un modello ospitato dal catalogo corrente: 
export OLLAMA_API_KEY='<your-ollama-cloud-api-key>'

OPENCLAW_LIVE_TEST=1 \
OPENCLAW_LIVE_OLLAMA=1 \
OPENCLAW_LIVE_OLLAMA_BASE_URL=https://ollama.com \
OPENCLAW_LIVE_OLLAMA_MODEL=glm-5.1:cloud \
OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=1 \
pnpm test:live -- extensions/ollama/ollama.live.test.ts
Lo smoke test cloud esegue testo, stream nativo e ricerca web. Salta gli embedding per impostazione predefinita per https://ollama.com perché le chiavi API di Ollama Cloud potrebbero non autorizzare /api/embed. Imposta OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1 quando vuoi esplicitamente che il test live fallisca se la chiave cloud configurata non può usare l’endpoint embed. Per aggiungere un nuovo modello, scaricalo semplicemente con Ollama: 
ollama pull mistral
Il nuovo modello verrà rilevato automaticamente e sarà disponibile per l’uso.
Se imposti esplicitamente models.providers.ollama, o configuri un provider remoto personalizzato come models.providers.ollama-cloud con api: "ollama", il rilevamento automatico viene saltato e devi definire i modelli manualmente. I provider personalizzati loopback come http://127.0.0.2:11434 vengono comunque trattati come locali. Vedi la sezione di configurazione esplicita qui sotto.

​
Inferenza locale su Node

Gli agenti possono delegare un’attività breve a un modello Ollama installato su un Node desktop o server associato. Prompt e risposta attraversano la connessione Gateway/Node autenticata esistente; la richiesta del modello viene eseguita sul Node selezionato rispetto al suo endpoint Ollama loopback standard (http://127.0.0.1:11434).
1

Avvia Ollama sul Node

Scarica almeno un modello chat e mantieni Ollama in esecuzione:
ollama pull qwen3:0.6b
ollama list
2

Connetti l'host Node

Sulla stessa macchina di Ollama, connetti un host Node al Gateway:
openclaw node run \
  --host <gateway-host> \
  --port 18789 \
  --display-name "Local inference"
Approva il nuovo dispositivo e i suoi comandi Node dichiarati sull’host Gateway, quindi verifica il Node:
openclaw devices list
openclaw devices approve <deviceRequestId>
openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status --connected
Sia una prima connessione sia un upgrade che aggiunge i comandi Ollama possono attivare l’approvazione dei comandi Node. Se il Node si connette senza pubblicizzare ollama.models e ollama.chat, controlla di nuovo openclaw nodes pending.
3

Chiedi a un agente di usare l'inferenza locale

Il Plugin Ollama incluso espone lo strumento node_inference. Gli agenti usano prima action: "discover", poi action: "run" con un Node e un modello restituiti. Se è connesso esattamente un Node compatibile, run può omettere il Node.Per esempio: “Scopri i modelli Ollama sui miei Node, poi usa il modello caricato più veloce per riassumere questo testo.”
Il rilevamento legge /api/tags, controlla le capacità di /api/show e usa /api/ps quando disponibile per classificare prima i modelli già caricati. Restituisce solo modelli chat locali compatibili: le righe Ollama Cloud e i modelli solo embedding sono esclusi. Ogni esecuzione chiede a Ollama di disabilitare il thinking del modello e limita l’output a 512 token, a meno che la chiamata dello strumento non richieda un valore maxTokens diverso. Alcuni modelli, come GPT-OSS, non supportano la disattivazione del thinking e potrebbero comunque usare token di ragionamento. Per mantenere Ollama in esecuzione su un Node senza renderlo disponibile agli agenti, imposta quanto segue nella configurazione usata da quell’host Node: 
openclaw config set plugins.entries.ollama.config.nodeInference.enabled false
Se il Node usa il comando in primo piano openclaw node run dalla configurazione sopra, arresta quel processo ed esegui di nuovo il comando. Se usa un servizio Node installato, esegui openclaw node restart. Il Node smette di pubblicizzare ollama.models e ollama.chat; Ollama stesso e il provider Ollama del Gateway rimangono invariati. Imposta il valore a true e riavvia il Node per pubblicizzare di nuovo l’inferenza locale. Una superficie di comandi modificata potrebbe richiedere approvazione tramite openclaw nodes pending dopo la riconnessione. Puoi verificare gli stessi comandi Node senza un turno dell’agente: 
openclaw nodes invoke \
  --node "Local inference" \
  --command ollama.models \
  --params '{}' \
  --invoke-timeout 90000 \
  --timeout 100000

openclaw nodes invoke \
  --node "Local inference" \
  --command ollama.chat \
  --params '{"model":"qwen3:0.6b","prompt":"Reply with exactly: pong","maxTokens":32,"timeoutMs":120000}' \
  --invoke-timeout 130000 \
  --timeout 140000
L’inferenza locale su Node non riutilizza intenzionalmente un models.providers.ollama.baseUrl remoto o cloud. Avvia Ollama sull’endpoint loopback standard del Node. I comandi Node sono disponibili per impostazione predefinita sugli host Node macOS, Linux e Windows e rimangono soggetti alla normale policy di associazione e comandi dei Node.

​
Visione e descrizione delle immagini

Il Plugin Ollama incluso registra Ollama come provider di comprensione media con supporto per immagini. Questo consente a OpenClaw di instradare richieste esplicite di descrizione immagini e impostazioni predefinite configurate dei modelli immagine tramite modelli di visione Ollama locali o ospitati. Per la visione locale, scarica un modello che supporta le immagini: 
ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
Poi verifica con la CLI infer: 
openclaw infer image describe \
  --file ./photo.jpg \
  --model ollama/qwen2.5vl:7b \
  --json
--model deve essere un riferimento completo <provider/model>. Quando è impostato, openclaw infer image describe prova prima quel modello invece di saltare la descrizione perché il modello supporta la visione nativa. Se la chiamata al modello fallisce, OpenClaw può continuare tramite i agents.defaults.imageModel.fallbacks configurati; gli errori di preparazione di file o URL falliscono comunque prima dei tentativi di fallback. Usa infer image describe quando vuoi il flusso del provider di comprensione immagini di OpenClaw, agents.defaults.imageModel configurato e la forma dell’output di descrizione immagini. Usa infer model run --file quando vuoi una prova grezza di modello multimodale con un prompt personalizzato e una o più immagini. Per rendere Ollama il modello predefinito di comprensione immagini per i media in ingresso, configura agents.defaults.imageModel: 
{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}
Preferisci il riferimento completo ollama/<model>. Se lo stesso modello è elencato sotto models.providers.ollama.models con input: ["text", "image"] e nessun altro provider immagine configurato espone quell’ID modello semplice, OpenClaw normalizza anche un riferimento imageModel semplice come qwen2.5vl:7b in ollama/qwen2.5vl:7b. Se più di un provider immagine configurato ha lo stesso ID semplice, usa esplicitamente il prefisso del provider. I modelli di visione locali lenti possono richiedere un timeout di comprensione immagini più lungo rispetto ai modelli cloud. Possono anche arrestarsi in modo anomalo o fermarsi quando Ollama prova ad allocare l’intero contesto di visione pubblicizzato su hardware limitato. Imposta un timeout di capacità e limita num_ctx nella voce del modello quando ti serve solo un normale turno di descrizione immagini: 
{
  models: {
    providers: {
      ollama: {
        models: [
          {
            id: "qwen2.5vl:7b",
            name: "qwen2.5vl:7b",
            input: ["text", "image"],
            params: { num_ctx: 2048, keep_alive: "1m" },
          },
        ],
      },
    },
  },
  tools: {
    media: {
      image: {
        timeoutSeconds: 180,
        models: [{ provider: "ollama", model: "qwen2.5vl:7b", timeoutSeconds: 300 }],
      },
    },
  },
}
Questo timeout si applica alla comprensione immagini in ingresso e allo strumento esplicito image che l’agente può chiamare durante un turno. Il models.providers.ollama.timeoutSeconds a livello di provider controlla comunque la protezione della richiesta HTTP Ollama sottostante per le normali chiamate di modello. Verifica dal vivo lo strumento immagine esplicito rispetto a Ollama locale con: 
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
  pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts
Se definisci manualmente models.providers.ollama.models, contrassegna i modelli di visione con il supporto all’input immagine: 
{
  id: "qwen2.5vl:7b",
  name: "qwen2.5vl:7b",
  input: ["text", "image"],
  contextWindow: 128000,
  maxTokens: 8192,
}
OpenClaw rifiuta le richieste di descrizione immagini per modelli che non sono contrassegnati come compatibili con immagini. Con il rilevamento implicito, OpenClaw lo legge da Ollama quando /api/show segnala una capacità di visione.

​
Configurazione

Il percorso di abilitazione più semplice solo locale avviene tramite variabile d’ambiente:
export OLLAMA_API_KEY="ollama-local"
Se OLLAMA_API_KEY è impostata, puoi omettere apiKey nella voce del provider e OpenClaw la compilerà per i controlli di disponibilità.

​
Ricette comuni

Usali come punti di partenza e sostituisci gli ID dei modelli con i nomi esatti da ollama list o openclaw models list --provider ollama.
Usalo quando Ollama viene eseguito sulla stessa macchina del Gateway e vuoi che OpenClaw rilevi automaticamente i modelli installati.
ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4
Questo percorso mantiene la configurazione minimale. Non aggiungere un blocco models.providers.ollama a meno che tu non voglia definire i modelli manualmente.
Usa URL Ollama nativi per gli host LAN. Non aggiungere /v1.
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            reasoning: true,
            input: ["text"],
            params: {
              num_ctx: 32768,
              thinking: false,
              keep_alive: "15m",
            },
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/qwen3.5:9b" },
    },
  },
}
contextWindow è il budget di contesto lato OpenClaw. params.num_ctx viene inviato a Ollama per la richiesta. Mantienili allineati quando il tuo hardware non può eseguire l’intero contesto pubblicizzato del modello.
Usalo quando non esegui un demone locale e vuoi usare direttamente i modelli Ollama ospitati.
export OLLAMA_API_KEY="your-ollama-api-key"

{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [
          {
            id: "kimi-k2.5:cloud",
            name: "kimi-k2.5:cloud",
            reasoning: false,
            input: ["text", "image"],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/kimi-k2.5:cloud" },
    },
  },
}
Usalo quando un demone Ollama locale o LAN ha effettuato l’accesso con ollama signin e deve servire sia modelli locali sia modelli :cloud.
ollama signin
ollama pull gemma4

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        models: [
          { id: "gemma4", name: "gemma4", input: ["text"] },
          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/gemma4",
        fallbacks: ["ollama/kimi-k2.5:cloud"],
      },
    },
  },
}
Usa ID provider personalizzati quando hai più di un server Ollama. Ogni provider ha il proprio host, i propri modelli, l’autenticazione, il timeout e i riferimenti ai modelli.
{
  models: {
    providers: {
      "ollama-fast": {
        baseUrl: "http://mini.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],
      },
      "ollama-large": {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 420,
        contextWindow: 131072,
        maxTokens: 16384,
        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama-fast/gemma4",
        fallbacks: ["ollama-large/qwen3.5:27b"],
      },
    },
  },
}
Quando OpenClaw invia la richiesta, il prefisso del provider attivo viene rimosso, quindi ollama-large/qwen3.5:27b arriva a Ollama come qwen3.5:27b.
Alcuni modelli locali possono rispondere a prompt semplici, ma faticano con l’intera superficie degli strumenti dell’agente. Inizia limitando strumenti e contesto prima di modificare le impostazioni globali del runtime.
{
  agents: {
    list: [
      {
        id: "local",
        experimental: {
          localModelLean: true,
        },
        model: { primary: "ollama/gemma4" },
      },
    ],
  },
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [
          {
            id: "gemma4",
            name: "gemma4",
            input: ["text"],
            params: { num_ctx: 32768 },
            compat: { supportsTools: false },
          },
        ],
      },
    },
  },
}
Usa compat.supportsTools: false solo quando il modello o il server fallisce in modo affidabile sugli schemi degli strumenti. Scambia capacità dell’agente con stabilità. localModelLean rimuove browser, Cron e strumenti di messaggistica dalla superficie diretta dell’agente e, per impostazione predefinita, sposta i cataloghi più grandi dietro controlli strutturati di ricerca strumenti, tranne quando un’esecuzione deve mantenere la semantica di consegna diretta dei messaggi; non modifica però il contesto runtime di Ollama né la modalità di pensiero. Abbinalo a params.num_ctx esplicito e params.thinking: false per piccoli modelli di pensiero in stile Qwen che entrano in loop o consumano il budget di risposta nel ragionamento nascosto.

​
Selezione del modello

Una volta configurati, tutti i tuoi modelli Ollama sono disponibili: 
{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}
Sono supportati anche ID provider Ollama personalizzati. Quando un riferimento al modello usa il prefisso del provider attivo, come ollama-spark/qwen3:32b, OpenClaw rimuove solo quel prefisso prima di chiamare Ollama, così il server riceve qwen3:32b. Per modelli locali lenti, preferisci la regolazione delle richieste con ambito provider prima di aumentare il timeout dell’intero runtime dell’agente: 
{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}
timeoutSeconds si applica alla richiesta HTTP del modello, inclusi configurazione della connessione, header, streaming del corpo e interruzione totale del recupero protetto. params.keep_alive viene inoltrato a Ollama come keep_alive di primo livello nelle richieste native /api/chat; impostalo per modello quando il tempo di caricamento del primo turno è il collo di bottiglia.

​
Verifica rapida

# Ollama daemon visible to this machine
curl http://127.0.0.1:11434/api/tags

# OpenClaw catalog and selected model
openclaw models list --provider ollama
openclaw models status

# Direct model smoke
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: ok"
Per host remoti, sostituisci 127.0.0.1 con l’host usato in baseUrl. Se curl funziona ma OpenClaw no, verifica se il Gateway viene eseguito su una macchina, un container o un account di servizio diverso. OpenClaw supporta Ollama Web Search come provider web_search incluso.
ProprietàDettaglio
HostUsa l’host Ollama configurato (models.providers.ollama.baseUrl se impostato, altrimenti http://127.0.0.1:11434); https://ollama.com usa direttamente l’API ospitata
AuthSenza chiave per host Ollama locali con accesso effettuato; OLLAMA_API_KEY o autenticazione provider configurata per la ricerca diretta su https://ollama.com o host protetti da autenticazione
RequisitoGli host locali/self-hosted devono essere in esecuzione e aver effettuato l’accesso con ollama signin; la ricerca ospitata diretta richiede baseUrl: "https://ollama.com" più una vera chiave API Ollama
Scegli Ollama Web Search durante openclaw onboard o openclaw configure --section web, oppure imposta: 
{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}
Per la ricerca ospitata diretta tramite Ollama Cloud: 
{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [{ id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text"] }],
      },
    },
  },
  tools: {
    web: {
      search: { provider: "ollama" },
    },
  },
}
Per un demone locale con accesso effettuato, OpenClaw usa il proxy /api/experimental/web_search del demone. Per https://ollama.com, chiama direttamente l’endpoint ospitato /api/web_search.
Per la configurazione completa e i dettagli di comportamento, vedi Ollama Web Search.

​
Configurazione avanzata

La chiamata degli strumenti non è affidabile in modalità compatibile con OpenAI. Usa questa modalità solo se ti serve il formato OpenAI per un proxy e non dipendi dal comportamento nativo di chiamata degli strumenti.
Se devi invece usare l’endpoint compatibile con OpenAI (ad esempio, dietro un proxy che supporta solo il formato OpenAI), imposta esplicitamente api: "openai-completions":
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: true, // default: true
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}
Questa modalità potrebbe non supportare simultaneamente streaming e chiamata degli strumenti. Potresti dover disabilitare lo streaming con params: { streaming: false } nella configurazione del modello.Quando api: "openai-completions" viene usato con Ollama, OpenClaw inietta options.num_ctx per impostazione predefinita, così Ollama non torna silenziosamente a una finestra di contesto di 4096. Se il tuo proxy/upstream rifiuta campi options sconosciuti, disabilita questo comportamento:
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: false,
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}
Per i modelli rilevati automaticamente, OpenClaw usa la finestra di contesto segnalata da Ollama quando disponibile, inclusi valori PARAMETER num_ctx più grandi da Modelfile personalizzati. Altrimenti ripiega sulla finestra di contesto predefinita di Ollama usata da OpenClaw.Puoi impostare valori predefiniti contextWindow, contextTokens e maxTokens a livello di provider per ogni modello sotto quel provider Ollama, quindi sovrascriverli per modello quando necessario. contextWindow è il budget di prompt e Compaction di OpenClaw. Le richieste native Ollama lasciano options.num_ctx non impostato a meno che tu non configuri esplicitamente params.num_ctx, così Ollama può applicare il proprio valore predefinito basato sul modello, su OLLAMA_CONTEXT_LENGTH o sulla VRAM. Per limitare o forzare il contesto di runtime per richiesta di Ollama senza ricostruire un Modelfile, imposta params.num_ctx; i valori non validi, zero, negativi e non finiti vengono ignorati. Se hai aggiornato una configurazione precedente che usava solo contextWindow o maxTokens per forzare un contesto di richiesta nativo Ollama, esegui openclaw doctor --fix per copiare quei budget espliciti del provider o del modello in params.num_ctx. L’adattatore Ollama compatibile con OpenAI continua a inserire options.num_ctx per impostazione predefinita dal params.num_ctx o dal contextWindow configurato; disabilitalo con injectNumCtxForOpenAICompat: false se il tuo upstream rifiuta options.Le voci dei modelli nativi Ollama accettano anche le opzioni comuni di runtime Ollama sotto params, incluse temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread e use_mmap. OpenClaw inoltra solo le chiavi di richiesta Ollama, quindi parametri di runtime OpenClaw come streaming non vengono esposti a Ollama. Usa params.think o params.thinking per inviare think Ollama di primo livello; false disabilita il ragionamento a livello API per modelli di ragionamento in stile Qwen.
{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        models: [
          {
            id: "llama3.3",
            contextWindow: 131072,
            maxTokens: 65536,
            params: {
              num_ctx: 32768,
              temperature: 0.7,
              top_p: 0.9,
              thinking: false,
            },
          }
        ]
      }
    }
  }
}
Anche agents.defaults.models["ollama/<model>"].params.num_ctx funziona. Se sono configurati entrambi, la voce esplicita del modello del provider ha la precedenza sul valore predefinito dell’agente.
Per i modelli nativi Ollama, OpenClaw inoltra il controllo del ragionamento come Ollama si aspetta: think di primo livello, non options.think. I modelli rilevati automaticamente la cui risposta /api/show include la capability thinking espongono /think low, /think medium, /think high e /think max; i modelli senza ragionamento espongono solo /think off.
openclaw agent --model ollama/gemma4 --thinking off
openclaw agent --model ollama/gemma4 --thinking low
Puoi anche impostare un valore predefinito del modello:
{
  agents: {
    defaults: {
      models: {
        "ollama/gemma4": {
          thinking: "low",
        },
      },
    },
  },
}
params.think o params.thinking per modello possono disabilitare o forzare il ragionamento dell’API Ollama per uno specifico modello configurato. OpenClaw conserva quei parametri espliciti del modello quando l’esecuzione attiva ha solo il valore predefinito implicito off; i comandi di runtime diversi da off, come /think medium, continuano a sovrascrivere l’esecuzione attiva.
OpenClaw considera per impostazione predefinita capaci di ragionamento i modelli con nomi come deepseek-r1, reasoning o think.
ollama pull deepseek-r1:32b
Non è necessaria alcuna configurazione aggiuntiva. OpenClaw li contrassegna automaticamente.
Ollama è gratuito ed eseguito localmente, quindi tutti i costi dei modelli sono impostati a 0 $. Questo vale sia per i modelli rilevati automaticamente sia per quelli definiti manualmente.
Il Plugin Ollama incluso registra un provider di embedding della memoria per la ricerca in memoria. Usa l’URL di base Ollama configurato e la chiave API, chiama l’endpoint corrente /api/embed di Ollama e raggruppa più frammenti di memoria in una richiesta input quando possibile.Quando proxy.enabled=true, le richieste di embedding della memoria Ollama verso l’esatta origine local loopback dell’host derivata dal baseUrl configurato usano il percorso diretto protetto di OpenClaw invece del proxy forward gestito. Il nome host configurato deve essere esso stesso localhost o un literal IP di loopback; i nomi DNS che si risolvono semplicemente in loopback continuano a usare il percorso del proxy gestito. Anche gli host Ollama LAN, tailnet, di rete privata e pubblici restano sul percorso del proxy gestito. I reindirizzamenti verso un altro host o porta non ereditano la fiducia. Gli operatori possono comunque impostare l’opzione globale proxy.loopbackMode: "proxy" per inviare il traffico di loopback attraverso il proxy, oppure proxy.loopbackMode: "block" per negare le connessioni di loopback prima di aprire una connessione; consulta Proxy gestito per l’effetto a livello di processo di questa impostazione.
ProprietàValore
Modello predefinitonomic-embed-text
Pull automaticoSì — il modello di embedding viene scaricato automaticamente se non è presente localmente
Gli embedding in fase di query usano prefissi di recupero per i modelli che li richiedono o li raccomandano, inclusi nomic-embed-text, qwen3-embedding e mxbai-embed-large. I batch dei documenti di memoria restano grezzi, così gli indici esistenti non richiedono una migrazione di formato.Per selezionare Ollama come provider di embedding per la ricerca in memoria:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        remote: {
          // Default for Ollama. Raise on larger hosts if reindexing is too slow.
          nonBatchConcurrency: 1,
        },
      },
    },
  },
}
Per un host di embedding remoto, mantieni l’autenticazione limitata a quell’host:
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        model: "nomic-embed-text",
        remote: {
          baseUrl: "http://gpu-box.local:11434",
          apiKey: "ollama-local",
          nonBatchConcurrency: 2,
        },
      },
    },
  },
}
L’integrazione Ollama di OpenClaw usa per impostazione predefinita la API nativa Ollama (/api/chat), che supporta pienamente streaming e chiamata di strumenti contemporaneamente. Non è necessaria alcuna configurazione speciale.Per le richieste native /api/chat, OpenClaw inoltra anche il controllo del ragionamento direttamente a Ollama: /think off e openclaw agent --thinking off inviano think: false di primo livello a meno che sia configurato un valore esplicito del modello params.think/params.thinking, mentre /think low|medium|high inviano la stringa di effort think di primo livello corrispondente. /think max viene mappato sull’effort nativo più alto di Ollama, think: "high".
Se devi usare l’endpoint compatibile con OpenAI, consulta la sezione “Modalità legacy compatibile con OpenAI” sopra. Streaming e chiamata di strumenti potrebbero non funzionare contemporaneamente in quella modalità.

​
Risoluzione dei problemi

Su WSL2 con NVIDIA/CUDA, l’installer Linux ufficiale di Ollama crea un’unità systemd ollama.service con Restart=always. Se quel servizio si avvia automaticamente e carica un modello supportato da GPU durante l’avvio di WSL2, Ollama può bloccare memoria dell’host mentre il modello viene caricato. Il recupero memoria di Hyper-V non riesce sempre a recuperare quelle pagine bloccate, quindi Windows può terminare la VM WSL2, systemd avvia di nuovo Ollama e il ciclo si ripete.Evidenze comuni:
  • riavvii o terminazioni ripetuti di WSL2 dal lato Windows
  • CPU elevata in app.slice o ollama.service poco dopo l’avvio di WSL2
  • SIGTERM da systemd invece di un evento Linux OOM-killer
OpenClaw registra un avviso di avvio quando rileva WSL2, ollama.service abilitato con Restart=always e marker CUDA visibili.Mitigazione:
sudo systemctl disable ollama
Aggiungi questo a %USERPROFILE%\.wslconfig sul lato Windows, quindi esegui wsl --shutdown:
[experimental]
autoMemoryReclaim=disabled
Imposta un keep-alive più breve nell’ambiente del servizio Ollama, oppure avvia Ollama manualmente solo quando ne hai bisogno:
export OLLAMA_KEEP_ALIVE=5m
ollama serve
Consulta ollama/ollama#11317.
Assicurati che Ollama sia in esecuzione, di aver impostato OLLAMA_API_KEY (o un profilo di autenticazione) e di non aver definito una voce esplicita models.providers.ollama:
ollama serve
Verifica che l’API sia accessibile:
curl http://localhost:11434/api/tags
Se il tuo modello non è elencato, scarica il modello localmente oppure definiscilo esplicitamente in models.providers.ollama.
ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model
Controlla che Ollama sia in esecuzione sulla porta corretta:
# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve
Verifica dalla stessa macchina e dallo stesso runtime che esegue il Gateway:
openclaw gateway status --deep
curl http://ollama-host:11434/api/tags
Cause comuni:
  • baseUrl punta a localhost, ma il Gateway è in esecuzione in Docker o su un altro host.
  • L’URL usa /v1, che seleziona il comportamento compatibile con OpenAI invece di Ollama nativo.
  • L’host remoto richiede modifiche al firewall o al binding LAN sul lato Ollama.
  • Il modello è presente sul daemon del tuo laptop ma non sul daemon remoto.
Di solito significa che il provider sta usando la modalità compatibile con OpenAI o che il modello non riesce a gestire gli schemi degli strumenti.Preferisci la modalità nativa Ollama:
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434",
        api: "ollama",
      },
    },
  },
}
Se un piccolo modello locale continua a non riuscire con gli schemi degli strumenti, imposta compat.supportsTools: false su quella voce di modello e riprova.
Le risposte Kimi/GLM ospitate che sono lunghe sequenze di simboli non linguistici vengono trattate come output del provider non riuscito invece che come risposta riuscita dell’assistente. Questo consente alla normale logica di retry, fallback o gestione degli errori di intervenire senza persistere il testo corrotto nella sessione.Se accade ripetutamente, acquisisci il nome grezzo del modello, il file di sessione corrente e se l’esecuzione ha usato Cloud + Local o Cloud only, quindi prova una nuova sessione e un modello di fallback:
openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --json
openclaw models set ollama/gemma4
I modelli locali grandi possono richiedere un primo caricamento lungo prima che lo streaming inizi. Mantieni il timeout limitato al provider Ollama e, facoltativamente, chiedi a Ollama di mantenere il modello caricato tra un turno e l’altro:
{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}
Se l’host stesso è lento ad accettare connessioni, timeoutSeconds estende anche il timeout di connessione Undici protetto per questo provider.
Molti modelli Ollama dichiarano contesti più grandi di quanto il tuo hardware possa eseguire comodamente. Ollama nativo usa il contesto runtime predefinito di Ollama, a meno che tu non imposti params.num_ctx. Limita sia il budget di OpenClaw sia il contesto della richiesta di Ollama quando vuoi una latenza prevedibile per il primo token:
{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            params: { num_ctx: 32768, thinking: false },
          },
        ],
      },
    },
  },
}
Riduci prima contextWindow se OpenClaw sta inviando un prompt troppo grande. Riduci params.num_ctx se Ollama sta caricando un contesto runtime troppo grande per la macchina. Riduci maxTokens se la generazione dura troppo a lungo.
Ulteriore assistenza: Risoluzione dei problemi e FAQ.

​
Correlati

Provider di modelli

Panoramica di tutti i provider, dei riferimenti ai modelli e del comportamento di failover.

Selezione del modello

Come scegliere e configurare i modelli.

Ricerca web Ollama

Dettagli completi di configurazione e comportamento per la ricerca web basata su Ollama.

Configurazione

Riferimento completo della configurazione.