Ollama

Gli URL Ollama di loopback, rete privata, .local e con solo nome host non richiedono un vero token bearer. OpenClaw utilizza 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 apiKey del provider. Per l'utilizzo diretto in hosting, preferire 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ò utilizzare apiKey: "ollama-local"; i sotto-agenti risolvono tale marcatore tramite l'hook del provider Ollama anziché considerarlo una credenziale mancante. agents.defaults.memorySearch.provider può anche puntare a un id provider personalizzato affinché gli embedding utilizzino quell'endpoint Ollama.

auth-profiles.json memorizza la credenziale per un id provider; inserire le impostazioni dell'endpoint (baseUrl, api, modelli, intestazioni, timeout) in models.providers.<id>. I vecchi file piatti come { "ollama-windows": { "apiKey": "ollama-local" } } non sono un formato di runtime; openclaw doctor --fix li riscrive in un profilo canonico con chiave API ollama-windows:default, creando un backup. Un valore baseUrl in quel 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 solo all'host di tale provider.
• agents.*.memorySearch.remote.apiKey viene inviata solo al relativo host remoto per gli embedding.
• Un semplice valore di ambiente OLLAMA_API_KEY viene trattato come convenzione di Ollama Cloud e, per impostazione predefinita, non viene inviato agli host locali o self-hosted.

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

Nessun daemon 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 l'ID provider dedicato ollama-cloud anziché questa struttura, vedere 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 (ripiegando su un prefisso ollama/ semplice) 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. Limitare gli strumenti e il 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 },          },        ],      },    },  },}

Usare compat.supportsTools: false solo quando il modello o il server presenta regolarmente errori con gli schemi degli strumenti: si sacrifica la capacità dell'agente in cambio di stabilità. localModelLean rimuove dalla superficie diretta dell'agente gli strumenti pesanti per browser, cron, messaggistica, generazione di contenuti multimediali, voce e PDF, salvo quando sono richiesti esplicitamente, e colloca i cataloghi più grandi dietro Tool Search. Non modifica il contesto di runtime o la modalità di ragionamento di Ollama. Abbinarlo 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.

Impostare api: "openai-completions" esplicitamente 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 params: { streaming: false } sul modello.

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

{  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 dei Modelfile personalizzati; altrimenti ripiega sulla finestra di contesto Ollama predefinita di OpenClaw.

contextWindow, contextTokens e maxTokens a livello di provider impostano i valori predefiniti per ogni modello di tale provider e possono essere sovrascritti per 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 delle richieste native, eseguire openclaw doctor --fix per copiarli in params.num_ctx. L'adattatore compatibile con OpenAI inserisce ancora options.num_ctx per impostazione predefinita dalla configurazione params.num_ctx o contextWindow; disabilitarlo con injectNumCtxForOpenAICompat: false se il servizio upstream rifiuta options.

Le voci dei modelli nativi accettano anche le opzioni comuni del runtime Ollama in params, inoltrate come options /api/chat native: 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 di richiesta di primo livello anziché in options. OpenClaw inoltra solo queste chiavi di richiesta Ollama, quindi i parametri esclusivi del runtime come streaming non vengono mai inviati a Ollama. Usare params.think (o params.thinking) per impostare think di primo livello; false disabilita il ragionamento a livello di 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,            },          }        ]      }    }  }}

Funziona anche agents.defaults.models["ollama/<model>"].params.num_ctx per modello; la voce esplicita del modello del provider ha la precedenza se sono impostati entrambi.

OpenClaw inoltra il ragionamento come previsto da Ollama: think di primo livello, non options.think. I modelli rilevati automaticamente il cui /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 impostare un valore predefinito per il modello:

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

Le impostazioni params.think/params.thinking per modello possono disabilitare o forzare il ragionamento dell'API per un modello specifico. OpenClaw conserva tale 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 come reasoning: false; una richiesta think: false viene sempre inviata a prescindere.

I modelli denominati deepseek-r1, reasoning, reason o think vengono 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. Utilizza l'URL di base e la chiave API di Ollama configurati, chiama /api/embed e raggruppa più segmenti di memoria in un'unica richiesta input, quando possibile.

Quando proxy.enabled=true, le richieste di embedding dirette all'esatta origine di loopback locale dell'host derivata dal valore baseUrl configurato utilizzano il percorso diretto protetto di OpenClaw anziché il proxy di inoltro gestito. Il nome host configurato deve essere localhost o un indirizzo IP letterale di loopback: i nomi DNS che si limitano a risolversi in loopback continuano a utilizzare il percorso del proxy gestito. Gli host Ollama su LAN, tailnet, rete privata e rete pubblica rimangono 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: consultare Proxy gestito.

Gli embedding al momento della query utilizzano 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, pertanto gli indici esistenti non richiedono alcuna migrazione del formato.

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

Per un host di embedding remoto, limitare l'ambito dell'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 utilizza per impostazione predefinita l'API nativa (/api/chat), che supporta contemporaneamente streaming e 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 superiore, a meno che non sia configurato esplicitamente params.think/params.thinking; /think low|medium|high invia la stringa di intensità corrispondente; /think max corrisponde all'intensità massima di Ollama, think: "high".

In WSL2 con NVIDIA/CUDA, il programma di installazione ufficiale di Ollama per Linux 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.

Segnali: riavvii o arresti ripetuti di WSL2, utilizzo elevato della CPU in app.slice o ollama.service subito dopo l'avvio di WSL2 e SIGTERM da systemd anziché dall'OOM killer 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, aggiungere quanto segue a %USERPROFILE%\.wslconfig, quindi eseguire wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

In alternativa, ridurre il keep-alive o avviare Ollama manualmente solo quando necessario:

export OLLAMA_KEEP_ALIVE=5mollama serve

Consultare ollama/ollama#11317.

Verificare 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

Scaricare il modello localmente oppure definirlo esplicitamente in models.providers.ollama:

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

Eseguire 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 utilizza /v1, selezionando il comportamento compatibile con OpenAI anziché quello nativo di Ollama.
• L'host remoto richiede modifiche al firewall o all'associazione LAN.
• Il modello è presente nel demone 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. È preferibile 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, impostare compat.supportsTools: false nella voce di tale modello ed eseguire nuovamente il test.

Le risposte Kimi/GLM ospitate costituite da lunghe sequenze di simboli non linguistici vengono considerate chiamate al provider non riuscite anziché risposte riuscite, in modo che entrino in funzione i normali meccanismi di nuovo tentativo, fallback e gestione degli errori, evitando di salvare testo danneggiato nella sessione.

Se il problema si ripresenta, acquisire il nome del modello, il file della sessione corrente e verificare se l'esecuzione ha utilizzato Cloud + Local o Cloud only, quindi provare una nuova sessione e un modello di fallback:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Rispondi esattamente con: ok" --jsonopenclaw models set ollama/gemma4

I modelli locali di grandi dimensioni possono richiedere molto tempo per il primo caricamento. Limitare il timeout al provider Ollama e, facoltativamente, 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 protetto per questo provider.

Molti modelli dichiarano contesti più ampi di quelli che l'hardware può gestire agevolmente. Ollama nativo utilizza il proprio valore predefinito di runtime, a meno che non sia impostato params.num_ctx. Limitare sia il budget di OpenClaw sia il contesto delle richieste di 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 },          },        ],      },    },  },}

Ridurre contextWindow se OpenClaw invia un prompt troppo grande. Ridurre params.num_ctx se il contesto di runtime di Ollama è troppo grande per la macchina. Ridurre maxTokens se la generazione dura troppo a lungo.