Ollama

Gli URL Ollama di local loopback, rete privata, .local e con semplice nome host non richiedono un vero token bearer. OpenClaw usa il marcatore ollama-local per questi casi.

Gli host remoti pubblici e https://ollama.com richiedono una credenziale reale: OLLAMA_API_KEY, un profilo di autenticazione o la proprietà apiKey del provider. Per l'uso diretto del servizio ospitato, preferisci il provider ollama-cloud.

Un provider personalizzato con api: "ollama" segue le stesse regole. Ad esempio, un provider ollama-remote indirizzato a un host LAN privato può usare apiKey: "ollama-local"; i sotto-agenti risolvono tale marcatore tramite l'hook del provider Ollama anziché considerarlo una credenziale mancante. Anche agents.defaults.memorySearch.provider può fare riferimento a un id provider personalizzato affinché gli embedding usino quell'endpoint Ollama.

auth-profiles.json archivia la credenziale per un id provider; inserisci le impostazioni dell'endpoint (baseUrl, api, modelli, intestazioni, timeout) in models.providers.<id>. I vecchi file piatti come { "ollama-windows": { "apiKey": "ollama-local" } } non costituiscono un formato di runtime; openclaw doctor --fix li riscrive come profilo canonico con chiave API ollama-windows:default, creando un backup. Un valore baseUrl in tale file precedente è superfluo e deve essere spostato nella configurazione del provider.

L'autenticazione bearer per gli embedding di memoria Ollama è limitata all'host per cui è stata dichiarata:

• Una chiave a livello di provider viene inviata esclusivamente all'host di quel provider.
• agents.*.memorySearch.remote.apiKey viene inviata esclusivamente al relativo host remoto per gli embedding.
• Un semplice valore della variabile d'ambiente OLLAMA_API_KEY viene considerato conforme alla convenzione di Ollama Cloud e, per impostazione predefinita, non viene inviato agli host locali o auto-ospitati.

Ollama sulla stessa macchina del Gateway, rilevato automaticamente:

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

Non aggiungere un blocco models.providers.ollama a meno che non siano necessari modelli manuali.

{  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 rappresenta il budget di contesto di OpenClaw; params.num_ctx viene inviato a Ollama. Mantienili allineati quando l'hardware non è in grado di eseguire il modello con l'intero contesto dichiarato.

Nessun demone locale, modelli ospitati direttamente:

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

Per usare l'ID provider dedicato ollama-cloud al posto di questa struttura, consulta Ollama Cloud.

ID provider personalizzati quando si esegue più di un server Ollama; ciascuno dispone di host, modelli, autenticazione e timeout propri.

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

OpenClaw rimuove il prefisso del provider attivo (usando come ripiego un prefisso semplice ollama/) prima di chiamare Ollama, quindi ollama-large/qwen3.5:27b raggiunge Ollama come qwen3.5:27b.

Alcuni modelli locali gestiscono prompt semplici, ma hanno difficoltà con l'intera superficie degli strumenti dell'agente. Limita gli strumenti e il contesto prima di modificare le impostazioni globali di 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 presenta sistematicamente errori con gli schemi degli strumenti: questa opzione sacrifica le capacità dell'agente in favore della stabilità. localModelLean rimuove dalla superficie diretta dell'agente gli strumenti più pesanti per browser, cron, messaggi, generazione di contenuti multimediali, voce e PDF, salvo quando siano richiesti esplicitamente, e colloca i cataloghi più grandi dietro la ricerca degli strumenti. Non modifica il contesto di runtime né la modalità di ragionamento di Ollama. Abbinalo a params.num_ctx e params.thinking: false per i piccoli modelli di ragionamento in stile Qwen che entrano in ciclo o consumano il proprio budget nel ragionamento nascosto.

Imposta esplicitamente api: "openai-completions" per un proxy dietro /v1/chat/completions:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // valore predefinito: true        apiKey: "ollama-local",        models: [...]      }    }  }}

Questa modalità potrebbe non supportare contemporaneamente lo streaming e la chiamata degli strumenti; potrebbe essere necessario impostare params: { streaming: false } sul modello.

OpenClaw inserisce options.num_ctx per impostazione predefinita in questa modalità, affinché Ollama non ripieghi silenziosamente su un contesto di 4096 token. Se il proxy rifiuta campi options sconosciuti, disabilitalo:

{  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 indicata da /api/show, inclusi i valori PARAMETER num_ctx più grandi provenienti da Modelfile personalizzati; altrimenti usa come ripiego la finestra di contesto Ollama predefinita di OpenClaw.

contextWindow, contextTokens e maxTokens a livello di provider impostano i valori predefiniti per ogni modello di quel provider e possono essere sovrascritti per ciascun modello. contextWindow è il budget di prompt/compaction proprio di OpenClaw. Le richieste native /api/chat lasciano options.num_ctx non impostato, a meno che non si imposti esplicitamente params.num_ctx, quindi Ollama applica il proprio valore predefinito basato sul modello, su OLLAMA_CONTEXT_LENGTH o sulla VRAM; i valori params.num_ctx non validi, pari a zero, negativi o non finiti vengono ignorati. Se una configurazione precedente usava solo contextWindow/maxTokens per forzare il contesto della richiesta nativa, esegui openclaw doctor --fix per copiarli in params.num_ctx. L'adattatore compatibile con OpenAI continua a inserire options.num_ctx per impostazione predefinita in base a params.num_ctx o contextWindow configurato; disabilitalo con injectNumCtxForOpenAICompat: false se il servizio a monte rifiuta options.

Le voci dei modelli nativi accettano inoltre le comuni opzioni di runtime Ollama in params, inoltrate come options native di /api/chat: num_keep, seed, num_predict, top_k, top_p, min_p, typical_p, repeat_last_n, temperature, repeat_penalty, presence_penalty, frequency_penalty, stop, num_batch, num_gpu, main_gpu, use_mmap e num_thread. Alcune chiavi (format, keep_alive, truncate, shift) vengono inoltrate come campi della richiesta di livello superiore anziché come options annidate. OpenClaw inoltra solo queste chiavi di richiesta Ollama, quindi i parametri esclusivamente di runtime, come streaming, non vengono mai inviati a Ollama. Usa params.think (o params.thinking) per impostare think al livello superiore; false disabilita il ragionamento a livello API per i 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 per modello funziona; la voce esplicita del modello nel provider ha la precedenza se sono impostate entrambe.

OpenClaw inoltra il ragionamento come previsto da Ollama: think al livello superiore, non options.think. I modelli rilevati automaticamente per i quali /api/show segnala una capacità 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 offopenclaw agent --model ollama/gemma4 --thinking low

Oppure imposta un valore predefinito per il modello:

{  agents: {    defaults: {      models: {        "ollama/gemma4": {          thinking: "low",        },      },    },  },}

params.think/params.thinking per modello può disabilitare o forzare il ragionamento dell'API per un modello specifico. OpenClaw conserva questa configurazione esplicita quando l'esecuzione attiva ha soltanto il valore predefinito implicito off; un comando di runtime diverso da off, come /think medium, continua ad avere la precedenza. Una richiesta di ragionamento con valore true non viene mai inviata a un modello contrassegnato esplicitamente con reasoning: false; una richiesta think: false viene sempre inviata.

I modelli denominati deepseek-r1, reasoning, reason o think sono considerati per impostazione predefinita capaci di ragionamento, senza necessità di configurazione aggiuntiva:

ollama pull deepseek-r1:32b

Ollama viene eseguito localmente ed è gratuito, quindi tutti i costi dei modelli sono 0 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 nella memoria. Usa l'URL di base e la chiave API di Ollama configurati, chiama /api/embed e, quando possibile, raggruppa più segmenti di memoria in un'unica richiesta input.

Quando proxy.enabled=true, le richieste di embedding all'origine local loopback esatta dell'host, derivata dal baseUrl configurato, usano il percorso diretto protetto di OpenClaw anziché il proxy di inoltro gestito. Il nome host configurato deve essere esso stesso localhost o un indirizzo IP di loopback letterale: i nomi DNS che si risolvono semplicemente in loopback continuano a usare il percorso del proxy gestito. Gli host Ollama su LAN, tailnet, rete privata e rete pubblica restano sempre sul percorso del proxy gestito e i reindirizzamenti verso un altro host o un'altra porta non ereditano l'attendibilità. proxy.loopbackMode: "proxy" instrada comunque il traffico di loopback attraverso il proxy; proxy.loopbackMode: "block" lo nega prima della connessione: consulta Proxy gestito.

Gli embedding in fase di query usano prefissi di recupero per i modelli che li richiedono o li consigliano: nomic-embed-text, qwen3-embedding e mxbai-embed-large. I batch di documenti rimangono invariati, quindi gli indici esistenti non richiedono alcuna migrazione del formato.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Valore predefinito per Ollama. Aumentalo sugli host più potenti se la reindicizzazione è troppo lenta.          nonBatchConcurrency: 1,        },      },    },  },}

Per un host di embedding remoto, limita l'autenticazione a tale host:

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        model: "nomic-embed-text",        remote: {          baseUrl: "http://gpu-box.local:11434",          apiKey: "ollama-local",          nonBatchConcurrency: 2,        },      },    },  },}

Ollama usa per impostazione predefinita l'API nativa (/api/chat), che supporta contemporaneamente lo streaming e la chiamata degli strumenti, senza necessità di configurazione speciale.

Per le richieste native, il controllo del ragionamento viene inoltrato direttamente: /think off e openclaw agent --thinking off inviano think: false al livello principale, a meno che non sia configurato un valore esplicito per params.think/params.thinking; /think low|medium|high invia la stringa corrispondente al livello di intensità; /think max corrisponde al livello massimo di Ollama, think: "high".

Su WSL2 con NVIDIA/CUDA, il programma di installazione Linux ufficiale di Ollama crea un'unità systemd ollama.service con Restart=always. Se tale servizio si avvia automaticamente e carica un modello basato su GPU durante l'avvio di WSL2, Ollama può bloccare la memoria dell'host durante il caricamento; il recupero della memoria di Hyper-V non riesce sempre a recuperare tali pagine, quindi Windows può terminare la VM WSL2, systemd riavvia Ollama e il ciclo si ripete.

Indizi: riavvii o terminazioni ripetuti di WSL2, utilizzo elevato della CPU in app.slice o ollama.service subito dopo l'avvio di WSL2 e SIGTERM da systemd anziché dal terminatore OOM di Linux.

OpenClaw registra un avviso all'avvio quando rileva WSL2, ollama.service abilitato con Restart=always e indicatori CUDA visibili.

Mitigazione:

sudo systemctl disable ollama

Sul lato Windows, aggiungi quanto segue a %USERPROFILE%\.wslconfig, quindi esegui wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

In alternativa, riduci il tempo di mantenimento attivo oppure avvia Ollama manualmente solo quando necessario:

export OLLAMA_KEEP_ALIVE=5mollama serve

Consulta ollama/ollama#11317.

Verifica che Ollama sia in esecuzione, che OLLAMA_API_KEY (o un profilo di autenticazione) sia impostato e che models.providers.ollama non sia definito esplicitamente:

ollama servecurl http://localhost:11434/api/tags

Scarica il modello localmente oppure definiscilo esplicitamente in models.providers.ollama:

ollama list  # Mostra ciò che è installatoollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Oppure un altro modello

Esegui la verifica dalla stessa macchina e dallo stesso runtime che eseguono il Gateway:

openclaw gateway status --deepcurl http://ollama-host:11434/api/tags

Cause comuni:

• baseUrl punta a localhost, ma il Gateway viene eseguito in Docker o su un altro host.
• L'URL usa /v1, selezionando il comportamento compatibile con OpenAI anziché quello nativo di Ollama.
• L'host remoto richiede modifiche al firewall o al binding LAN.
• Il modello è presente nel daemon del portatile, ma non in quello remoto.

In genere il provider è in modalità compatibile con OpenAI oppure il modello non è in grado di gestire gli schemi degli strumenti. Preferisci la modalità nativa:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434",        api: "ollama",      },    },  },}

Se un piccolo modello locale continua a non gestire correttamente gli schemi degli strumenti, imposta compat.supportsTools: false nella voce del modello e ripeti il test.

Le risposte di Kimi/GLM in hosting costituite da lunghe sequenze di simboli non linguistici vengono considerate una chiamata al provider non riuscita anziché una risposta valida, in modo che intervenga la normale gestione dei nuovi tentativi, del fallback o degli errori, invece di salvare testo danneggiato nella sessione.

Se il problema si ripresenta, acquisisci il nome del modello, il file della sessione corrente e indica 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" --jsonopenclaw models set ollama/gemma4

I modelli locali di grandi dimensioni possono richiedere molto tempo al primo caricamento. Limita il timeout al provider Ollama e, facoltativamente, mantieni 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 le connessioni, timeoutSeconds estende anche il timeout di connessione protetto per questo provider.

Molti modelli dichiarano contesti più grandi di quelli che l'hardware può gestire agevolmente. Ollama nativo usa il proprio valore predefinito di runtime, a meno che non sia impostato params.num_ctx. Limita sia il budget di OpenClaw sia il contesto della richiesta Ollama per ottenere una latenza prevedibile del 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 contextWindow se OpenClaw invia un prompt troppo lungo. Riduci params.num_ctx se il contesto di runtime di Ollama è troppo grande per la macchina. Riduci maxTokens se la generazione dura troppo a lungo.