Ollama

Gli host Ollama locali e LAN non richiedono un token bearer reale. OpenClaw usa il marcatore locale ollama-local solo per URL di base Ollama loopback, di rete privata, .local e con nome host semplice.

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.

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 LAN privata può usare apiKey: "ollama-local" e i sub-agent risolveranno quel marcatore tramite l'hook del provider Ollama invece di trattarlo come una credenziale mancante. Anche la ricerca in memoria può 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, intestazioni, timeout) in models.providers.<id>. I vecchi file di profilo di autenticazione piatti, come { "ollama-windows": { "apiKey": "ollama-local" } }, non sono un formato runtime; esegui openclaw doctor --fix per riscriverli nel profilo canonico con 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 di embedding remoto.
• Un valore env puro OLLAMA_API_KEY viene trattato come convenzione di Ollama Cloud, e per impostazione predefinita non viene inviato a host locali o autogestiti.

Usa questo quando Ollama gira sulla stessa macchina del Gateway e vuoi che OpenClaw rilevi automaticamente i modelli installati.

ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

Questo percorso mantiene la configurazione minima. 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 dichiarato del modello.

Usa questo quando non esegui un daemon locale e vuoi modelli Ollama 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" },
    },
  },
}

Usa questo quando un daemon Ollama locale o LAN è autenticato con ollama signin e deve servire sia modelli locali sia modelli :cloud.

ollama signin
ollama 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 host, modelli, autenticazione, timeout e riferimenti modello 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"],
      },
    },
  },
}

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 avere difficoltà con l'intera superficie degli strumenti agente. Inizia limitando strumenti e contesto prima di modificare le impostazioni runtime globali.

{
  agents: {
    defaults: {
      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 gli strumenti browser, Cron e messaggi dalla superficie dell'agente, ma non modifica il contesto di runtime o la modalità di pensiero di Ollama. 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 invece devi usare l'endpoint compatibile con OpenAI (per 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 streaming e chiamata degli strumenti contemporaneamente. Potresti dover 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 ripiega silenziosamente su una finestra di contesto 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 scoperti automaticamente, OpenClaw usa la finestra di contesto riportata da Ollama quando disponibile, inclusi i valori PARAMETER num_ctx più grandi dai Modelfile personalizzati. Altrimenti ripiega sulla finestra di contesto Ollama predefinita usata da OpenClaw.

Puoi impostare valori predefiniti a livello di provider per contextWindow, contextTokens e maxTokens 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 modello, OLLAMA_CONTEXT_LENGTH o il valore predefinito basato 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. L'adattatore Ollama compatibile con OpenAI inserisce ancora options.num_ctx per impostazione predefinita da params.num_ctx o contextWindow configurati; disabilitalo con injectNumCtxForOpenAICompat: false se il tuo upstream rifiuta options.

Le voci dei modelli Ollama nativi 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 chiavi di richiesta Ollama, quindi i parametri di runtime OpenClaw come streaming non vengono passati a Ollama. Usa params.think o params.thinking per inviare think Ollama di primo livello; false disabilita il pensiero a livello API per modelli di pensiero 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. Se sono configurati entrambi, la voce esplicita del modello del provider prevale sul valore predefinito dell'agente.

Per i modelli Ollama nativi, OpenClaw inoltra il controllo del pensiero come Ollama si aspetta: think di primo livello, non options.think. I modelli scoperti automaticamente la cui risposta /api/show include la capacità thinking espongono /think low, /think medium, /think high e /think max; i modelli senza pensiero espongono solo /think off.

openclaw agent --model ollama/gemma4 --thinking off
openclaw 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 può disabilitare o forzare il pensiero API Ollama per uno specifico modello configurato. OpenClaw preserva 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, sovrascrivono comunque l'esecuzione attiva.

OpenClaw tratta i modelli con nomi come deepseek-r1, reasoning o think come capaci di ragionamento per impostazione predefinita.

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 si applica sia ai modelli scoperti automaticamente sia a quelli definiti manualmente.

Il Plugin Ollama integrato registra un provider di embedding per la memoria per ricerca in memoria. Usa l'URL base Ollama configurato e la chiave API, chiama l'endpoint corrente /api/embed di Ollama e raggruppa più frammenti di memoria in un'unica richiesta input quando possibile.

Gli embedding al momento della 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 di 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'auth con ambito limitato 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 Ollama nativa (/api/chat), che supporta pienamente streaming e chiamata agli 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 al livello principale, a meno che non sia configurato un valore esplicito del modello params.think/params.thinking, mentre /think low|medium|high invia la stringa di impegno think corrispondente al livello principale. /think max viene mappato al massimo impegno nativo 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 quel servizio si avvia automaticamente e carica un modello con GPU durante l'avvio di WSL2, Ollama può bloccare la memoria dell'host mentre il modello viene caricato. Il recupero della 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.

Prove comuni:

• riavvii o terminazioni ripetute 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 OOM-killer Linux

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

Mitigazione:

sudo systemctl disable ollama

Aggiungilo 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 ti serve:

export OLLAMA_KEEP_ALIVE=5m
ollama 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 la 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 installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model

Controlla che Ollama sia in esecuzione sulla porta corretta:

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

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

openclaw gateway status --deep
curl 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, 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.

Questo 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à Ollama nativa:

{
  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 del modello e riprova.

Le risposte ospitate di Kimi/GLM 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 nuovo tentativo, fallback o gestione degli errori di subentrare senza salvare il testo corrotto nella sessione.

Se succede ripetutamente, acquisisci il nome grezzo del modello, il file della 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" --json
openclaw models set ollama/gemma4

I modelli locali di grandi dimensioni possono richiedere un lungo caricamento iniziale 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 valore predefinito del contesto runtime di Ollama, a meno che non imposti params.num_ctx. Limita sia il budget di OpenClaw sia il contesto della richiesta Ollama quando vuoi 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 },
          },
        ],
      },
    },
  },
}

Abbassa prima contextWindow se OpenClaw sta inviando troppo prompt. Abbassa params.num_ctx se Ollama sta caricando un contesto runtime troppo grande per la macchina. Abbassa maxTokens se la generazione dura troppo a lungo.