Ollama

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.

Usalo quando Ollama viene eseguito sulla stessa macchina del Gateway e vuoi che OpenClaw rilevi automaticamente i modelli installati.

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw 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 signinollama 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.

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 offopenclaw 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.

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".

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=5mollama 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 installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

Controlla che Ollama sia in esecuzione sulla porta corretta:

# Check if Ollama is runningps aux | grep ollama # Or restart Ollamaollama serve

Verifica dalla stessa macchina e dallo stesso runtime che esegue il Gateway:

openclaw gateway status --deepcurl 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" --jsonopenclaw 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.