Vai al contenuto principale

​
Ollama

Ollama è un runtime LLM locale che rende semplice eseguire modelli open-source sulla tua macchina. OpenClaw si integra con l’API nativa di Ollama (/api/chat), supporta streaming e tool calling e può rilevare automaticamente i modelli Ollama locali quando abiliti OLLAMA_API_KEY (o un profilo auth) e non definisci una voce esplicita models.providers.ollama.
Utenti di Ollama remoto: non usare l’URL compatibile con OpenAI /v1 (http://host:11434/v1) con OpenClaw. Questo interrompe il tool calling e i modelli possono produrre JSON di tool grezzo come testo normale. Usa invece l’URL dell’API nativa di Ollama: baseUrl: "http://host:11434" (senza /v1).

​
Avvio rapido

​
Onboarding (consigliato)

Il modo più rapido per configurare Ollama è tramite l’onboarding: 
openclaw onboard
Seleziona Ollama dall’elenco dei provider. L’onboarding:
  1. Chiederà il base URL di Ollama dove la tua istanza è raggiungibile (predefinito http://127.0.0.1:11434).
  2. Ti permetterà di scegliere Cloud + Local (modelli cloud e locali) oppure Local (solo modelli locali).
  3. Aprirà un flusso di accesso via browser se scegli Cloud + Local e non hai effettuato l’accesso a ollama.com.
  4. Rileverà i modelli disponibili e suggerirà i valori predefiniti.
  5. Eseguirà automaticamente il pull del modello selezionato se non è disponibile localmente.
È supportata anche la modalità non interattiva: 
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk
Facoltativamente puoi specificare un base URL o un modello personalizzati: 
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

​
Configurazione manuale

  1. Installa Ollama: https://ollama.com/download
  2. Esegui il pull di un modello locale se vuoi inferenza locale: 
ollama pull glm-4.7-flash
# oppure
ollama pull gpt-oss:20b
# oppure
ollama pull llama3.3
  1. Se vuoi anche i modelli cloud, effettua l’accesso:
ollama signin
  1. Esegui l’onboarding e scegli Ollama:
openclaw onboard
  • Local: solo modelli locali
  • Cloud + Local: modelli locali più modelli cloud
  • I modelli cloud come kimi-k2.5:cloud, minimax-m2.5:cloud e glm-5:cloud non richiedono un ollama pull locale
OpenClaw al momento suggerisce:
  • predefinito locale: glm-4.7-flash
  • predefiniti cloud: kimi-k2.5:cloud, minimax-m2.5:cloud, glm-5:cloud
  1. Se preferisci la configurazione manuale, abilita direttamente Ollama per OpenClaw (qualsiasi valore va bene; Ollama non richiede una chiave reale):
# Imposta la variabile d'ambiente
export OLLAMA_API_KEY="ollama-local"

# Oppure configura nel file di configurazione
openclaw config set models.providers.ollama.apiKey "ollama-local"
  1. Ispeziona o cambia modello:
openclaw models list
openclaw models set ollama/glm-4.7-flash
  1. Oppure imposta il predefinito nella configurazione:
{
  agents: {
    defaults: {
      model: { primary: "ollama/glm-4.7-flash" },
    },
  },
}

​
Rilevamento dei modelli (provider implicito)

Quando imposti OLLAMA_API_KEY (o un profilo auth) e non definisci models.providers.ollama, OpenClaw rileva i modelli dall’istanza Ollama locale su http://127.0.0.1:11434:
  • Interroga /api/tags
  • Usa lookup /api/show best-effort per leggere contextWindow quando disponibile
  • Contrassegna reasoning con un’euristica sul nome del modello (r1, reasoning, think)
  • Imposta maxTokens al limite massimo di token predefinito di Ollama usato da OpenClaw
  • Imposta tutti i costi a 0
Questo evita voci di modello manuali mantenendo il catalogo allineato con l’istanza Ollama locale. Per vedere 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à rilevato automaticamente e sarà disponibile all’uso. Se imposti esplicitamente models.providers.ollama, il rilevamento automatico viene saltato e dovrai definire i modelli manualmente (vedi sotto).

​
Configurazione

​
Configurazione di base (rilevamento implicito)

Il modo più semplice per abilitare Ollama è tramite variabile d’ambiente: 
export OLLAMA_API_KEY="ollama-local"

​
Configurazione esplicita (modelli manuali)

Usa la configurazione esplicita quando:
  • Ollama è in esecuzione su un altro host/porta.
  • Vuoi forzare specifiche finestre di contesto o elenchi di modelli.
  • Vuoi definizioni di modelli completamente manuali.
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host: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: 8192,
            maxTokens: 8192 * 10
          }
        ]
      }
    }
  }
}
Se OLLAMA_API_KEY è impostata, puoi omettere apiKey nella voce provider e OpenClaw la userà per i controlli di disponibilità.

​
Base URL personalizzato (configurazione esplicita)

Se Ollama è in esecuzione su un host o una porta diversi (la configurazione esplicita disabilita il rilevamento automatico, quindi definisci i modelli manualmente): 
{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434", // Nessun /v1 - usa l'URL dell'API nativa di Ollama
        api: "ollama", // Impostalo esplicitamente per garantire il comportamento nativo del tool calling
      },
    },
  },
}
Non aggiungere /v1 all’URL. Il percorso /v1 usa la modalità compatibile con OpenAI, in cui il tool calling non è affidabile. Usa il base URL di Ollama senza suffisso di percorso.

​
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"],
      },
    },
  },
}

​
Modelli cloud

I modelli cloud ti permettono di eseguire modelli ospitati nel cloud (per esempio kimi-k2.5:cloud, minimax-m2.5:cloud, glm-5:cloud) insieme ai tuoi modelli locali. Per usare i modelli cloud, seleziona la modalità Cloud + Local durante il setup. La procedura guidata controlla se hai effettuato l’accesso e apre un flusso di login via browser quando necessario. Se l’autenticazione non può essere verificata, la procedura guidata torna ai valori predefiniti dei modelli locali. Puoi anche effettuare l’accesso direttamente su ollama.com/signin. OpenClaw supporta anche Ollama Web Search come provider bundled web_search.
  • Usa l’host Ollama configurato (models.providers.ollama.baseUrl quando impostato, altrimenti http://127.0.0.1:11434).
  • Non richiede chiave.
  • Richiede che Ollama sia in esecuzione e che tu abbia effettuato l’accesso con ollama signin.
Scegli Ollama Web Search durante openclaw onboard oppure openclaw configure --section web, oppure imposta: 
{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}
Per i dettagli completi di setup e comportamento, vedi Ollama Web Search.

​
Avanzato

​
Modelli di reasoning

OpenClaw tratta per default come compatibili con il reasoning i modelli con nomi come deepseek-r1, reasoning o think: 
ollama pull deepseek-r1:32b

​
Costi dei modelli

Ollama è gratuito e gira localmente, quindi tutti i costi dei modelli sono impostati a $0.

​
Configurazione dello streaming

L’integrazione Ollama di OpenClaw usa per default l’API nativa di Ollama (/api/chat), che supporta pienamente streaming e tool calling contemporaneamente. Non è necessaria alcuna configurazione speciale.

​
Modalità legacy compatibile con OpenAI

Il tool calling non è affidabile in modalità compatibile con OpenAI. Usa questa modalità solo se hai bisogno del formato OpenAI per un proxy e non dipendi dal comportamento nativo del tool calling.
Se hai bisogno di usare invece 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, // predefinito: true
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}
Questa modalità potrebbe non supportare contemporaneamente streaming + tool calling. 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 default così Ollama non ricade silenziosamente su 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: [...]
      }
    }
  }
}

​
Finestre di contesto

Per i modelli rilevati automaticamente, OpenClaw usa la finestra di contesto riportata da Ollama quando disponibile, altrimenti usa la finestra di contesto predefinita di Ollama usata da OpenClaw. Puoi sovrascrivere contextWindow e maxTokens nella configurazione esplicita del provider.

​
Risoluzione dei problemi

​
Ollama non viene rilevato

Assicurati che Ollama sia in esecuzione, che tu abbia impostato OLLAMA_API_KEY (o un profilo auth) e che non abbia definito una voce esplicita models.providers.ollama: 
ollama serve
E che l’API sia accessibile: 
curl http://localhost:11434/api/tags

​
Nessun modello disponibile

Se il tuo modello non è elencato, puoi:
  • eseguire il pull del modello localmente, oppure
  • definire esplicitamente il modello in models.providers.ollama.
Per aggiungere modelli: 
ollama list  # Vedi cosa è installato
ollama pull glm-4.7-flash
ollama pull gpt-oss:20b
ollama pull llama3.3     # Oppure un altro modello

​
Connessione rifiutata

Controlla che Ollama sia in esecuzione sulla porta corretta: 
# Controlla se Ollama è in esecuzione
ps aux | grep ollama

# Oppure riavvia Ollama
ollama serve

​
Vedi anche