Vai al contenuto principale

​
Ollama

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 contro https://ollama.com, oppure Local only contro un host Ollama raggiungibile.
Utenti di Ollama remoto: non usare l’URL OpenAI-compatible /v1 (http://host:11434/v1) con OpenClaw. Questo interrompe il tool calling e i modelli possono produrre JSON di strumenti grezzo come testo normale. Usa invece l’URL dell’API nativa di Ollama: baseUrl: "http://host:11434" (senza /v1).

​
Per iniziare

Scegli il metodo e la modalità di configurazione che preferisci.
Ideale per: il percorso più rapido verso una configurazione funzionante di Ollama cloud o locale.
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 valori predefiniti cloud ospitati. Cloud + Local e Local only richiedono un URL base di Ollama, individuano i modelli disponibili ed eseguono automaticamente il pull del modello locale selezionato se non è ancora disponibile. Cloud + Local controlla 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 base o un 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 da Ollama.Usa Cloud + Local durante la configurazione. OpenClaw richiede l’URL base di Ollama, individua i modelli locali da quell’host e controlla se l’host ha effettuato l’accesso per l’accesso cloud con ollama signin. Quando l’host ha effettuato l’accesso, OpenClaw suggerisce anche valori predefiniti 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 in modalità solo locale finché non esegui ollama signin.

​
Individuazione dei modelli (provider implicito)

Quando imposti OLLAMA_API_KEY (o un profilo di autenticazione) e non definisci models.providers.ollama, OpenClaw individua i modelli dall’istanza Ollama locale su http://127.0.0.1:11434.
ComportamentoDettaglio
Query del catalogoInterroga /api/tags
Rilevamento delle capacitàUsa richieste /api/show best-effort per leggere contextWindow e rilevare le capacità (inclusa la visione)
Modelli visionI modelli con capacità vision riportata da /api/show vengono contrassegnati come capaci di elaborare immagini (input: ["text", "image"]), quindi OpenClaw inserisce automaticamente le immagini nel prompt
Rilevamento del reasoningContrassegna reasoning con un’euristica basata sul nome del modello (r1, reasoning, think)
Limiti di tokenImposta maxTokens al limite massimo di token predefinito di Ollama usato da OpenClaw
CostiImposta tutti i costi a 0
Questo evita inserimenti manuali dei modelli mantenendo il catalogo allineato con l’istanza Ollama locale. 
# Vedi quali modelli sono disponibili
ollama list
openclaw models list
Per aggiungere un nuovo modello, esegui semplicemente il pull con Ollama: 
ollama pull mistral
Il nuovo modello verrà individuato automaticamente e sarà disponibile per l’uso.
Se imposti models.providers.ollama esplicitamente, l’individuazione automatica viene saltata e devi definire i modelli manualmente. Vedi la sezione sulla configurazione esplicita qui sotto.

​
Configurazione

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

​
Selezione del modello

Una volta configurato, tutti i tuoi modelli Ollama sono disponibili: 
{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}
OpenClaw supporta Ollama Web Search come provider web_search incluso.
ProprietàDettaglio
HostUsa il tuo host Ollama configurato (models.providers.ollama.baseUrl quando impostato, altrimenti http://127.0.0.1:11434)
AutenticazioneSenza chiave
RequisitoOllama deve essere in esecuzione e avere effettuato l’accesso con ollama signin
Scegli Ollama Web Search durante openclaw onboard o openclaw configure --section web, oppure imposta: 
{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}
Per tutti i dettagli su configurazione e comportamento, vedi Ollama Web Search.

​
Configurazione avanzata

Il tool calling non è affidabile nella modalità OpenAI-compatible. Usa questa modalità solo se hai bisogno del formato OpenAI per un proxy e non dipendi dal comportamento nativo di tool calling.
Se invece devi usare l’endpoint OpenAI-compatible (ad esempio dietro un proxy che supporta solo il formato OpenAI), imposta api: "openai-completions" esplicitamente:
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: true, // predefinito: true
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}
Questa modalità potrebbe non supportare simultaneamente streaming e tool calling. Potrebbe essere necessario disabilitare lo streaming con params: { streaming: false } nella configurazione del modello.Quando api: "openai-completions" viene usato con Ollama, OpenClaw inserisce 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 individuati automaticamente, OpenClaw usa la finestra di contesto riportata da Ollama quando disponibile, altrimenti usa come fallback la finestra di contesto predefinita di Ollama usata da OpenClaw.Puoi sovrascrivere contextWindow e maxTokens nella configurazione esplicita del provider:
{
  models: {
    providers: {
      ollama: {
        models: [
          {
            id: "llama3.3",
            contextWindow: 131072,
            maxTokens: 65536,
          }
        ]
      }
    }
  }
}
OpenClaw considera per impostazione predefinita come capaci di reasoning 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 e viene eseguito localmente, quindi tutti i costi dei modelli sono impostati a $0. Questo vale sia per i modelli individuati automaticamente sia per quelli definiti manualmente.
Il Plugin Ollama incluso registra un provider di embedding della memoria per la ricerca nella memoria. Usa l’URL base di Ollama configurato e la chiave API.
ProprietàValore
Modello predefinitonomic-embed-text
Pull automaticoSì — il modello di embedding viene scaricato automaticamente se non è presente in locale
Per selezionare Ollama come provider di embedding per la ricerca nella memoria:
{
  agents: {
    defaults: {
      memorySearch: { provider: "ollama" },
    },
  },
}
L’integrazione Ollama di OpenClaw usa per impostazione predefinita l’API nativa di Ollama (/api/chat), che supporta pienamente streaming e tool calling simultaneamente. Non è necessaria alcuna configurazione speciale.
Se devi usare l’endpoint OpenAI-compatible, consulta la sezione “Modalità legacy OpenAI-compatible” sopra. Streaming e tool calling potrebbero non funzionare contemporaneamente in quella modalità.

​
Risoluzione dei problemi

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, esegui il pull del modello in locale oppure definiscilo esplicitamente in models.providers.ollama.
ollama list  # Vedi cosa è installato
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Oppure un altro modello
Verifica che Ollama sia in esecuzione sulla porta corretta:
# Verifica se Ollama è in esecuzione
ps aux | grep ollama

# Oppure riavvia Ollama
ollama serve
Ulteriore aiuto: 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.

Ollama Web Search

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

Configurazione

Riferimento completo della configurazione.