Ollama

Les URL Ollama de boucle locale, de réseau privé, en .local et avec un nom d’hôte simple ne nécessitent pas de véritable jeton porteur. OpenClaw utilise le marqueur ollama-local pour celles-ci.

Les hôtes publics distants et https://ollama.com nécessitent de véritables identifiants : OLLAMA_API_KEY, un profil d’authentification ou la propriété apiKey du fournisseur. Pour une utilisation hébergée directe, privilégiez le fournisseur ollama-cloud.

Un fournisseur personnalisé avec api: "ollama" suit les mêmes règles. Par exemple, un fournisseur ollama-remote pointant vers un hôte de réseau local privé peut utiliser apiKey: "ollama-local" ; les sous-agents résolvent ce marqueur au moyen du hook du fournisseur Ollama au lieu de le considérer comme un identifiant manquant. agents.defaults.memorySearch.provider peut également pointer vers un identifiant de fournisseur personnalisé afin que les plongements utilisent ce point de terminaison Ollama.

auth-profiles.json stocke les identifiants d’un identifiant de fournisseur ; placez les paramètres du point de terminaison (baseUrl, api, modèles, en-têtes, délais d’expiration) dans models.providers.<id>. Les anciens fichiers plats tels que { "ollama-windows": { "apiKey": "ollama-local" } } ne constituent pas un format d’exécution ; openclaw doctor --fix les réécrit sous la forme d’un profil canonique de clé d’API ollama-windows:default, avec une sauvegarde. Une valeur baseUrl dans cet ancien fichier est superflue et doit être déplacée vers la configuration du fournisseur.

L’authentification par jeton porteur pour les plongements de mémoire Ollama est limitée à l’hôte pour lequel elle a été déclarée :

• Une clé définie au niveau du fournisseur est envoyée uniquement à l’hôte de ce fournisseur.
• agents.*.memorySearch.remote.apiKey est envoyée uniquement à son hôte distant de plongements.
• Une valeur d’environnement OLLAMA_API_KEY seule est considérée comme suivant la convention d’Ollama Cloud et n’est pas envoyée par défaut aux hôtes locaux ou auto-hébergés.

Ollama sur la même machine que le Gateway, détecté automatiquement :

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

N’ajoutez pas de bloc models.providers.ollama, sauf si vous avez besoin de modèles manuels.

{  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 représente le budget de contexte d’OpenClaw ; params.num_ctx est envoyé à Ollama. Maintenez-les cohérents lorsque le matériel ne peut pas exécuter le modèle avec l’intégralité de son contexte annoncé.

Aucun démon local, modèles hébergés directement :

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

Pour utiliser l’identifiant de fournisseur dédié ollama-cloud au lieu de cette structure, consultez Ollama Cloud.

Utilisez des identifiants de fournisseur personnalisés lorsque vous exécutez plusieurs serveurs Ollama ; chacun dispose de son propre hôte, de ses propres modèles, de sa propre authentification et de son propre délai d’expiration.

{  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 retire le préfixe du fournisseur actif (avec repli sur un préfixe ollama/ simple) avant d’appeler Ollama, de sorte que ollama-large/qwen3.5:27b parvient à Ollama sous la forme qwen3.5:27b.

Certains modèles locaux gèrent les requêtes simples, mais rencontrent des difficultés avec l’ensemble complet des outils de l’agent. Limitez les outils et le contexte avant de modifier les paramètres globaux d’exécution :

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

Utilisez compat.supportsTools: false uniquement lorsque le modèle ou le serveur échoue systématiquement avec les schémas d’outils : cela sacrifie des capacités de l’agent au profit de la stabilité. localModelLean retire de l’interface directe de l’agent les outils lourds liés au navigateur, à Cron, aux messages, à la génération de médias, à la voix et aux PDF, sauf s’ils sont explicitement requis, et place les catalogues plus volumineux derrière Tool Search. Il ne modifie ni le contexte d’exécution d’Ollama ni le mode de raisonnement. Associez-le à params.num_ctx et à params.thinking: false pour les petits modèles de raisonnement de type Qwen qui bouclent ou consacrent leur budget au raisonnement masqué.

Définissez explicitement api: "openai-completions" pour un proxy placé derrière /v1/chat/completions :

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // valeur par défaut : true        apiKey: "ollama-local",        models: [...]      }    }  }}

Ce mode peut ne pas prendre en charge simultanément la diffusion et l’appel d’outils ; vous devrez peut-être définir params: { streaming: false } sur le modèle.

OpenClaw injecte options.num_ctx par défaut dans ce mode afin qu’Ollama ne se replie pas silencieusement sur un contexte de 4 096 jetons. Si votre proxy rejette les champs options inconnus, désactivez cette fonctionnalité :

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

Pour les modèles détectés automatiquement, OpenClaw utilise la fenêtre de contexte indiquée par /api/show, notamment les valeurs PARAMETER num_ctx supérieures provenant de Modelfiles personnalisés ; sinon, il se replie sur la fenêtre de contexte Ollama par défaut d’OpenClaw.

Les paramètres contextWindow, contextTokens et maxTokens au niveau du fournisseur définissent les valeurs par défaut de chaque modèle de ce fournisseur et peuvent être remplacés pour chaque modèle. contextWindow constitue le budget propre à OpenClaw pour les requêtes et la Compaction. Les requêtes natives /api/chat laissent options.num_ctx non défini, sauf si vous définissez explicitement params.num_ctx ; Ollama applique donc sa propre valeur par défaut issue du modèle, de OLLAMA_CONTEXT_LENGTH ou de la VRAM. Les valeurs params.num_ctx non valides, nulles, négatives ou non finies sont ignorées. Si une ancienne configuration utilisait uniquement contextWindow/maxTokens pour imposer le contexte des requêtes natives, exécutez openclaw doctor --fix afin de les copier dans params.num_ctx. L’adaptateur compatible avec OpenAI injecte toujours options.num_ctx par défaut à partir de params.num_ctx ou contextWindow configuré ; désactivez ce comportement avec injectNumCtxForOpenAICompat: false si le service en amont rejette options.

Les entrées de modèles natifs acceptent également les options d’exécution Ollama courantes sous params, transmises comme options natives de /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 et num_thread. Quelques clés (format, keep_alive, truncate, shift) sont transmises comme champs de requête de premier niveau plutôt que comme options imbriquées. OpenClaw ne transmet que ces clés de requête Ollama ; les paramètres propres à l’environnement d’exécution, tels que streaming, ne sont donc jamais envoyés à Ollama. Utilisez params.think (ou params.thinking) pour définir think au premier niveau ; false désactive le raisonnement au niveau de l’API pour les modèles de raisonnement de type 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,            },          }        ]      }    }  }}

Le paramètre agents.defaults.models["ollama/<model>"].params.num_ctx propre à chaque modèle fonctionne également ; l’entrée explicite du modèle du fournisseur l’emporte si les deux sont définis.

OpenClaw transmet le raisonnement comme Ollama l’attend : avec think au premier niveau, et non options.think. Les modèles détectés automatiquement dont /api/show indique une capacité thinking proposent /think low, /think medium, /think high et /think max ; les modèles sans raisonnement proposent uniquement /think off.

openclaw agent --model ollama/gemma4 --thinking offopenclaw agent --model ollama/gemma4 --thinking low

Vous pouvez également définir une valeur par défaut pour le modèle :

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

La configuration par modèle params.think/params.thinking peut désactiver ou forcer la réflexion de l’API pour un modèle précis. OpenClaw conserve cette configuration explicite lorsque l’exécution active ne possède que la valeur implicite par défaut off ; une commande d’exécution autre que off, telle que /think medium, la remplace toujours. Une demande de réflexion vraie n’est jamais envoyée à un modèle explicitement marqué reasoning: false ; une demande think: false est toujours envoyée quoi qu’il arrive.

Les modèles nommés deepseek-r1, reasoning, reason ou think sont considérés par défaut comme capables de raisonnement — aucune configuration supplémentaire n’est nécessaire :

ollama pull deepseek-r1:32b

Ollama s’exécute localement et est gratuit ; tous les coûts des modèles sont donc de 0, qu’ils soient détectés automatiquement ou définis manuellement.

Le plugin Ollama intégré enregistre un fournisseur de vectorisation de la mémoire pour la recherche en mémoire. Il utilise l’URL de base Ollama et la clé d’API configurées, appelle /api/embed et regroupe si possible plusieurs fragments de mémoire dans une seule requête input.

Lorsque proxy.enabled=true, les requêtes de vectorisation vers l’origine de local loopback exacte de l’hôte, dérivée de la valeur baseUrl configurée, utilisent le chemin direct protégé d’OpenClaw au lieu du proxy de transfert géré. Le nom d’hôte configuré doit lui-même être localhost ou une adresse IP littérale de bouclage — les noms DNS qui se résolvent simplement vers le bouclage utilisent toujours le chemin du proxy géré. Les hôtes Ollama du réseau local, du tailnet, d’un réseau privé ou public restent toujours sur le chemin du proxy géré, et les redirections vers un autre hôte ou port n’héritent pas de la confiance. proxy.loopbackMode: "proxy" achemine malgré tout le trafic de bouclage via le proxy ; proxy.loopbackMode: "block" le refuse avant la connexion — consultez Proxy géré.

Les vectorisations effectuées lors des requêtes utilisent des préfixes de récupération pour les modèles qui les exigent ou les recommandent : nomic-embed-text, qwen3-embedding et mxbai-embed-large. Les lots de documents restent bruts ; les index existants ne nécessitent donc aucune migration de format.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Valeur par défaut pour Ollama. Augmentez-la sur les hôtes plus puissants si la réindexation est trop lente.          nonBatchConcurrency: 1,        },      },    },  },}

Pour un hôte de vectorisation distant, limitez l’authentification à cet hôte :

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

Ollama utilise par défaut l’API native (/api/chat), qui prend en charge simultanément la diffusion en continu et l’appel d’outils — aucune configuration particulière n’est nécessaire.

Pour les requêtes natives, le contrôle de la réflexion est transmis directement : /think off et openclaw agent --thinking off envoient think: false au niveau supérieur, sauf si une valeur explicite params.think/params.thinking est configurée ; /think low|medium|high envoie la chaîne correspondant au niveau d’effort ; /think max correspond au niveau d’effort maximal d’Ollama, think: "high".

Sous WSL2 avec NVIDIA/CUDA, le programme d’installation Linux officiel d’Ollama crée une unité systemd ollama.service avec Restart=always. Si ce service démarre automatiquement et charge un modèle reposant sur le GPU pendant le démarrage de WSL2, Ollama peut immobiliser la mémoire de l’hôte pendant le chargement ; la récupération de mémoire d’Hyper-V ne peut pas toujours récupérer ces pages. Windows peut alors arrêter la machine virtuelle WSL2, systemd redémarre Ollama et la boucle se répète.

Indices : redémarrages ou arrêts répétés de WSL2, utilisation élevée du processeur dans app.slice ou ollama.service juste après le démarrage de WSL2, et signal SIGTERM provenant de systemd plutôt que du mécanisme d’arrêt pour mémoire insuffisante de Linux.

OpenClaw consigne un avertissement au démarrage lorsqu’il détecte WSL2, ollama.service activé avec Restart=always et des marqueurs CUDA visibles.

Mesure d’atténuation :

sudo systemctl disable ollama

Du côté de Windows, ajoutez ceci à %USERPROFILE%\.wslconfig, puis exécutez wsl --shutdown :

[experimental]autoMemoryReclaim=disabled

Vous pouvez également raccourcir la durée de maintien en vie ou démarrer Ollama manuellement uniquement lorsque cela est nécessaire :

export OLLAMA_KEEP_ALIVE=5mollama serve

Consultez ollama/ollama#11317.

Vérifiez qu’Ollama est en cours d’exécution, que OLLAMA_API_KEY (ou un profil d’authentification) est défini et que models.providers.ollama n’est pas défini explicitement :

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

Téléchargez le modèle localement ou définissez-le explicitement dans models.providers.ollama :

ollama list  # Afficher les modèles installésollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Ou un autre modèle

Effectuez la vérification depuis la machine et l’environnement d’exécution qui exécutent le Gateway :

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

Causes fréquentes :

• baseUrl pointe vers localhost, mais le Gateway s’exécute dans Docker ou sur un autre hôte.
• L’URL utilise /v1, ce qui sélectionne le comportement compatible avec OpenAI au lieu du comportement Ollama natif.
• L’hôte distant nécessite de modifier le pare-feu ou la liaison au réseau local.
• Le modèle se trouve dans le démon de votre ordinateur portable, mais pas dans celui de l’hôte distant.

En général, le fournisseur est en mode compatible avec OpenAI ou le modèle ne peut pas gérer les schémas d’outils. Préférez le mode natif :

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

Si un petit modèle local échoue encore avec les schémas d’outils, définissez compat.supportsTools: false pour l’entrée de ce modèle, puis refaites le test.

Les réponses Kimi/GLM hébergées constituées de longues suites de symboles non linguistiques sont traitées comme un échec de l’appel au fournisseur plutôt que comme une réponse réussie, afin que les mécanismes normaux de nouvelle tentative, de repli et de gestion des erreurs prennent le relais au lieu d’enregistrer du texte corrompu dans la session.

Si le problème se reproduit, relevez le nom du modèle, le fichier de session actuel et si l’exécution utilisait Cloud + Local ou Cloud only, puis essayez une nouvelle session et un modèle de repli :

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Répondez exactement : ok" --jsonopenclaw models set ollama/gemma4

Les grands modèles locaux peuvent nécessiter un long chargement initial. Limitez le délai d’attente au fournisseur Ollama et, si vous le souhaitez, maintenez le modèle chargé entre les tours :

{  models: {    providers: {      ollama: {        timeoutSeconds: 300,        models: [          {            id: "gemma4:26b",            name: "gemma4:26b",            params: { keep_alive: "15m" },          },        ],      },    },  },}

Si l’hôte lui-même est lent à accepter les connexions, timeoutSeconds prolonge également le délai de connexion protégé pour ce fournisseur.

De nombreux modèles annoncent des contextes plus grands que ce que votre matériel peut exécuter confortablement. Ollama natif utilise sa propre valeur d’exécution par défaut, sauf si params.num_ctx est défini. Limitez à la fois le budget d’OpenClaw et le contexte de requête d’Ollama afin d’obtenir une latence prévisible avant le premier jeton :

{  models: {    providers: {      ollama: {        contextWindow: 32768,        maxTokens: 8192,        models: [          {            id: "qwen3.5:9b",            name: "qwen3.5:9b",            params: { num_ctx: 32768, thinking: false },          },        ],      },    },  },}

Réduisez contextWindow si OpenClaw envoie une invite trop volumineuse. Réduisez params.num_ctx si le contexte d’exécution d’Ollama est trop grand pour la machine. Réduisez maxTokens si la génération dure trop longtemps.