Ollama

Les URL Ollama de bouclage, de réseau privé, .local et utilisant un nom d'hôte seul ne nécessitent pas de véritable jeton porteur. OpenClaw utilise le marqueur ollama-local pour celles-ci.

Les hôtes distants publics et https://ollama.com nécessitent de véritables identifiants : OLLAMA_API_KEY, un profil d'authentification ou la valeur 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 privé du réseau local peut utiliser apiKey: "ollama-local" ; les sous-agents résolvent ce marqueur par l'intermédiaire du hook du fournisseur Ollama au lieu de le considérer comme des identifiants manquants. 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é 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é au niveau du fournisseur est envoyée uniquement à l'hôte de ce fournisseur.
• agents.*.memorySearch.remote.apiKey est envoyé uniquement à son hôte distant de plongement.
• Une valeur d'environnement OLLAMA_API_KEY seule est considérée comme la convention 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 est le budget de contexte d’OpenClaw ; params.num_ctx est envoyé à Ollama. Maintenez-les alignés lorsque le matériel ne peut pas exécuter le contexte complet annoncé par le modèle.

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 plusieurs serveurs Ollama sont exécutés ; 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 invites 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 réduit les capacités de l’agent au profit de la stabilité. localModelLean retire de l’interface directe de l’agent les outils lourds de navigateur, de cron, de messagerie, de génération de médias, de voix et de PDF, sauf s’ils sont explicitement requis, et place les catalogues plus volumineux derrière la recherche d’outils. Cela ne modifie ni le contexte d’exécution d’Ollama ni son mode de réflexion. Associez-le à params.num_ctx et params.thinking: false pour les petits modèles de réflexion de type Qwen qui tournent en boucle ou consacrent leur budget au raisonnement masqué.

Définissez explicitement api: "openai-completions" pour un proxy situé 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 en continu 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 4096 jetons. Si votre proxy rejette les champs options inconnus, désactivez cette option :

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

Pour les modèles découverts automatiquement, OpenClaw utilise la fenêtre de contexte signalée par /api/show, y compris les valeurs PARAMETER num_ctx plus élevées provenant de Modelfiles personnalisés ; sinon, il utilise par défaut la fenêtre de contexte Ollama 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 correspond au budget d’invite et de Compaction propre à OpenClaw. Les requêtes /api/chat natives laissent options.num_ctx indéfini, sauf si vous définissez explicitement params.num_ctx, afin qu’Ollama applique sa propre valeur par défaut fondée sur le modèle, OLLAMA_CONTEXT_LENGTH ou 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 copier ces valeurs 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 cette option 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 /api/chat natives : 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 niveau supérieur plutôt que sous options. OpenClaw transmet uniquement ces clés de requête Ollama, de sorte que les paramètres propres à l’environnement d’exécution tels que streaming ne sont jamais envoyés à Ollama. Utilisez params.think (ou params.thinking) pour définir think au niveau supérieur ; false désactive la réflexion au niveau de l’API pour les modèles de réflexion 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,            },          }        ]      }    }  }}

La valeur agents.defaults.models["ollama/<model>"].params.num_ctx propre au modèle fonctionne également ; l’entrée de modèle explicite du fournisseur prévaut si les deux sont définies.

OpenClaw transmet la réflexion comme Ollama l’attend : think au niveau supérieur, et non options.think. Les modèles découverts automatiquement dont /api/show signale une capacité thinking exposent /think low, /think medium, /think high et /think max ; les modèles sans réflexion exposent uniquement /think off.

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

Ou définissez un modèle par défaut :

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

Les paramètres params.think/params.thinking propres à chaque modèle peuvent désactiver ou forcer le raisonnement de l’API pour un modèle spécifique. OpenClaw conserve cette configuration explicite lorsque l’exécution active ne possède que la valeur par défaut implicite off ; une commande d’exécution qui ne désactive pas le raisonnement, telle que /think medium, la remplace tout de même. Une demande de raisonnement 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 de modèle sont donc 0, tant pour les modèles détectés automatiquement que pour ceux définis manuellement.

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

Lorsque proxy.enabled=true, les requêtes d’embedding vers l’origine de bouclage locale à l’hôte exacte, dérivée de la valeur baseUrl configurée, utilisent le chemin direct protégé d’OpenClaw plutôt que le 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 une adresse de 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 publics restent toujours sur le chemin du proxy géré, et les redirections vers un autre hôte ou port n’héritent pas de cette confiance. proxy.loopbackMode: "proxy" fait tout de même transiter le trafic de bouclage par le proxy ; proxy.loopbackMode: "block" le refuse avant la connexion — consultez Proxy géré.

Les embeddings effectués au moment de la requête 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 d’embedding 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 le streaming et les appels d’outils — aucune configuration particulière n’est nécessaire.

Pour les requêtes natives, le contrôle du raisonnement est transmis directement : /think off et openclaw agent --thinking off envoient le paramètre de premier niveau think: false, sauf si une valeur explicite params.think/params.thinking est configurée ; /think low|medium|high envoie la chaîne d’effort correspondante ; /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 utilisant le GPU pendant le démarrage de WSL2, Ollama peut monopoliser 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, si bien que Windows peut 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 envoyé par systemd plutôt qu’une intervention du mécanisme OOM de Linux.

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

Mesure d’atténuation :

sudo systemctl disable ollama

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

[experimental]autoMemoryReclaim=disabled

Vous pouvez également réduire la durée de maintien en vie ou démarrer Ollama manuellement uniquement lorsque 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 même machine et le même environnement d’exécution que 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 plutôt que le comportement natif d’Ollama.
• L’hôte distant nécessite une modification du pare-feu ou de 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 traiter les schémas d’outils. Privilégiez 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 dans l’entrée de ce modèle et effectuez un nouveau 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 ; ainsi, la gestion normale des nouvelles tentatives, du repli ou des erreurs prend 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 par : ok" --jsonopenclaw models set ollama/gemma4

Le premier chargement des grands modèles locaux peut être long. Limitez le délai d’expiration au fournisseur Ollama et, si vous le souhaitez, conservez le modèle chargé entre les échanges :

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

Si l’hôte lui-même accepte lentement 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 token :

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