Ollama

Les hôtes Ollama locaux et LAN n’ont pas besoin d’un véritable jeton porteur. OpenClaw utilise le marqueur local ollama-local uniquement pour les URL de base Ollama en local loopback, sur réseau privé, en .local et avec nom d’hôte nu.

Les hôtes publics distants et Ollama Cloud (https://ollama.com) exigent un véritable identifiant via OLLAMA_API_KEY, un profil d’authentification ou apiKey du fournisseur. Pour une utilisation hébergée directe, privilégiez le fournisseur ollama-cloud.

Les identifiants de fournisseur personnalisés qui définissent api: "ollama" suivent les mêmes règles. Par exemple, un fournisseur ollama-remote qui pointe vers un hôte Ollama sur un LAN privé peut utiliser apiKey: "ollama-local", et les sous-agents résoudront ce marqueur via le hook du fournisseur Ollama au lieu de le traiter comme un identifiant manquant. La recherche en mémoire peut aussi définir agents.defaults.memorySearch.provider sur cet identifiant de fournisseur personnalisé afin que les embeddings utilisent le point de terminaison Ollama correspondant.

auth-profiles.json stocke l’identifiant pour un identifiant de fournisseur. Placez les paramètres de point de terminaison (baseUrl, api, identifiants de modèles, en-têtes, délais d’expiration) dans models.providers.<id>. Les anciens fichiers de profil d’authentification plats tels que { "ollama-windows": { "apiKey": "ollama-local" } } ne sont pas un format d’exécution ; exécutez openclaw doctor --fix pour les réécrire au format canonique de profil de clé API ollama-windows:default avec une sauvegarde. baseUrl dans ce fichier est du bruit de compatibilité et devrait être déplacé vers la configuration du fournisseur.

Quand Ollama est utilisé pour les embeddings de mémoire, l’authentification par porteur est limitée à l’hôte où elle a été déclarée :

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

Utilisez ceci quand Ollama s’exécute sur la même machine que le Gateway et que vous voulez qu’OpenClaw découvre automatiquement les modèles installés.

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

Ce parcours garde la configuration minimale. N’ajoutez pas de bloc models.providers.ollama, sauf si vous voulez définir les modèles manuellement.

Utilisez les URL Ollama natives pour les hôtes du LAN. N’ajoutez pas /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 est le budget de contexte côté OpenClaw. params.num_ctx est envoyé à Ollama pour la requête. Gardez-les alignés lorsque votre matériel ne peut pas exécuter le contexte complet annoncé par le modèle.

Utilisez ceci quand vous n’exécutez pas de démon local et que vous voulez accéder directement aux modèles Ollama hébergés.

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

Utilisez ceci quand un démon Ollama local ou LAN est connecté avec ollama signin et doit servir à la fois les modèles locaux et les modèles :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"],      },    },  },}

Utilisez des ID de fournisseurs personnalisés lorsque vous avez plusieurs serveurs Ollama. Chaque fournisseur obtient son propre hôte, ses modèles, son authentification, son délai d’expiration et ses références de modèle.

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

Quand OpenClaw envoie la requête, le préfixe du fournisseur actif est supprimé, de sorte que ollama-large/qwen3.5:27b arrive à Ollama sous la forme qwen3.5:27b.

Certains modèles locaux peuvent répondre à des prompts simples, mais ont des difficultés avec toute la surface des outils d’agent. Commencez par limiter 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 de façon fiable sur les schémas d’outils. Cela échange une partie des capacités de l’agent contre de la stabilité. localModelLean retire les outils de navigateur, Cron et messagerie de la surface directe de l’agent, et place par défaut les catalogues plus volumineux derrière des contrôles structurés de recherche d’outils, sauf lorsqu’une exécution doit conserver la sémantique de livraison directe des messages. Cela ne modifie toutefois ni le contexte d’exécution d’Ollama ni le mode de réflexion. Associez-le à params.num_ctx explicite et à params.thinking: false pour les petits modèles de réflexion de style Qwen qui bouclent ou dépensent leur budget de réponse en raisonnement masqué.

Si vous devez utiliser le point de terminaison compatible OpenAI à la place (par exemple derrière un proxy qui ne prend en charge que le format OpenAI), définissez explicitement api: "openai-completions" :

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

Ce mode peut ne pas prendre en charge simultanément le streaming et l’appel d’outils. Vous devrez peut-être désactiver le streaming avec params: { streaming: false } dans la configuration du modèle.

Lorsque api: "openai-completions" est utilisé avec Ollama, OpenClaw injecte options.num_ctx par défaut afin qu’Ollama ne revienne pas silencieusement à une fenêtre de contexte de 4096. Si votre proxy ou amont rejette les champs options inconnus, désactivez ce comportement :

{  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 Ollama lorsqu’elle est disponible, y compris les valeurs PARAMETER num_ctx plus grandes provenant de Modelfiles personnalisés. Sinon, il revient à la fenêtre de contexte Ollama par défaut utilisée par OpenClaw.

Vous pouvez définir des valeurs par défaut contextWindow, contextTokens et maxTokens au niveau du fournisseur pour chaque modèle sous ce fournisseur Ollama, puis les remplacer par modèle si nécessaire. contextWindow correspond au budget d’invite et de Compaction d’OpenClaw. Les requêtes Ollama natives laissent options.num_ctx non défini, sauf si vous configurez explicitement params.num_ctx, afin qu’Ollama puisse appliquer sa propre valeur par défaut basée sur le modèle, OLLAMA_CONTEXT_LENGTH ou la VRAM. Pour plafonner ou forcer le contexte d’exécution par requête d’Ollama sans reconstruire un Modelfile, définissez params.num_ctx ; les valeurs non valides, nulles, négatives et non finies sont ignorées. Si vous avez mis à niveau une ancienne configuration qui utilisait seulement contextWindow ou maxTokens pour forcer un contexte de requête Ollama native, exécutez openclaw doctor --fix pour copier ces budgets explicites de fournisseur ou de modèle dans params.num_ctx. L’adaptateur Ollama compatible OpenAI injecte toujours options.num_ctx par défaut à partir de params.num_ctx ou contextWindow configuré ; désactivez cela avec injectNumCtxForOpenAICompat: false si votre amont rejette options.

Les entrées de modèles Ollama natifs acceptent aussi les options d’exécution Ollama courantes sous params, notamment temperature, top_p, top_k, min_p, num_predict, stop, repeat_penalty, num_batch, num_thread et use_mmap. OpenClaw transmet uniquement les clés de requête Ollama, afin que les paramètres d’exécution OpenClaw comme streaming ne soient pas divulgués à Ollama. Utilisez params.think ou params.thinking pour envoyer le think Ollama de premier niveau ; false désactive la réflexion au niveau de l’API pour les modèles de réflexion de style 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,            },          }        ]      }    }  }}

agents.defaults.models["ollama/<model>"].params.num_ctx par modèle fonctionne également. Si les deux sont configurés, l’entrée explicite de modèle du fournisseur l’emporte sur la valeur par défaut de l’agent.

Pour les modèles Ollama natifs, OpenClaw transmet le contrôle de la réflexion comme Ollama l’attend : think au premier niveau, et non options.think. Les modèles découverts automatiquement dont la réponse /api/show inclut la capacité thinking exposent /think low, /think medium, /think high et /think max ; les modèles sans réflexion exposent seulement /think off.

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

Vous pouvez aussi définir une valeur par défaut de modèle :

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

params.think ou params.thinking par modèle peut désactiver ou forcer la réflexion de l’API Ollama pour un modèle configuré spécifique. OpenClaw préserve ces paramètres de modèle explicites quand l’exécution active n’a que la valeur implicite par défaut off ; les commandes d’exécution non désactivées comme /think medium remplacent toujours l’exécution active.

OpenClaw traite par défaut les modèles dont le nom contient par exemple deepseek-r1, reasoning ou think comme capables de raisonnement.

ollama pull deepseek-r1:32b

Aucune configuration supplémentaire n’est nécessaire. OpenClaw les marque automatiquement.

Ollama est gratuit et s’exécute localement, donc tous les coûts de modèle sont définis à 0 $. Cela s’applique aux modèles découverts automatiquement comme aux modèles définis manuellement.

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

Lorsque proxy.enabled=true, les requêtes d’embedding de mémoire Ollama vers l’origine local loopback exacte de l’hôte dérivée du baseUrl configuré 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 boucle locale ; les noms DNS qui se résolvent simplement vers la boucle locale utilisent toujours le chemin du proxy géré. Les hôtes Ollama LAN, tailnet, réseau privé et publics restent également sur le chemin du proxy géré. Les redirections vers un autre hôte ou port n’héritent pas de la confiance. Les opérateurs peuvent toujours définir le paramètre global proxy.loopbackMode: "proxy" pour envoyer le trafic de boucle locale via le proxy, ou proxy.loopbackMode: "block" pour refuser les connexions de boucle locale avant d’ouvrir une connexion ; consultez Proxy géré pour l’effet de ce paramètre à l’échelle du processus.

Les embeddings au moment de la requête utilisent des préfixes de récupération pour les modèles qui les exigent ou les recommandent, notamment nomic-embed-text, qwen3-embedding et mxbai-embed-large. Les lots de documents de mémoire restent bruts afin que les index existants ne nécessitent pas de migration de format.

Pour sélectionner Ollama comme fournisseur d’embeddings pour la recherche en mémoire :

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Default for Ollama. Raise on larger hosts if reindexing is too slow.          nonBatchConcurrency: 1,        },      },    },  },}

Pour un hôte d’embedding distant, gardez l’authentification limitée à cet hôte :

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

L’intégration Ollama d’OpenClaw utilise par défaut l’API Ollama native (/api/chat), qui prend entièrement en charge simultanément le streaming et l’appel d’outils. Aucune configuration particulière n’est nécessaire.

Pour les requêtes natives /api/chat, OpenClaw transmet aussi directement à Ollama le contrôle de la réflexion : /think off et openclaw agent --thinking off envoient think: false au premier niveau, sauf si une valeur explicite de modèle params.think/params.thinking est configurée, tandis que /think low|medium|high envoie la chaîne d’effort think de premier niveau correspondante. /think max correspond à l’effort natif le plus élevé d’Ollama, think: "high".

Sous WSL2 avec NVIDIA/CUDA, l’installateur 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 appuyé par GPU pendant le démarrage de WSL2, Ollama peut épingler la mémoire de l’hôte pendant le chargement du modèle. La récupération de mémoire Hyper-V ne peut pas toujours récupérer ces pages épinglées, donc Windows peut arrêter la VM WSL2, systemd redémarre Ollama, et la boucle se répète.

Indices courants :

• redémarrages ou arrêts répétés de WSL2 côté Windows
• CPU élevé dans app.slice ou ollama.service peu après le démarrage de WSL2
• SIGTERM provenant de systemd plutôt que d’un événement OOM-killer Linux

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

Atténuation :

sudo systemctl disable ollama

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

[experimental]autoMemoryReclaim=disabled

Définissez une durée keep-alive plus courte dans l’environnement du service Ollama, ou démarrez Ollama manuellement seulement lorsque vous en avez besoin :

export OLLAMA_KEEP_ALIVE=5mollama serve

Consultez ollama/ollama#11317.

Assurez-vous qu’Ollama est en cours d’exécution, que vous avez défini OLLAMA_API_KEY (ou un profil d’authentification), et que vous n’avez pas défini d’entrée explicite models.providers.ollama :

ollama serve

Vérifiez que l’API est accessible :

curl http://localhost:11434/api/tags

Si votre modèle n’est pas répertorié, récupérez le modèle localement ou définissez-le explicitement dans models.providers.ollama.

ollama list  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

Vérifiez qu’Ollama s’exécute sur le bon port :

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

Vérifiez depuis la même machine et le même runtime que ceux qui exécutent le Gateway :

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

Causes courantes :

• 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 OpenAI au lieu d’Ollama natif.
• L’hôte distant nécessite des modifications de pare-feu ou de liaison LAN côté Ollama.
• Le modèle est présent sur le daemon de votre ordinateur portable, mais pas sur le daemon distant.

Cela signifie généralement que le fournisseur utilise le mode compatible OpenAI ou que le modèle ne peut pas gérer les schémas d’outils.

Préférez le mode Ollama natif :

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

Si un petit modèle local échoue toujours sur les schémas d’outils, définissez compat.supportsTools: false sur cette entrée de modèle et retestez.

Les réponses Kimi/GLM hébergées qui sont longues et composées de suites de symboles non linguistiques sont traitées comme une sortie fournisseur échouée plutôt que comme une réponse d’assistant réussie. Cela permet à la logique normale de nouvelle tentative, de repli ou de gestion d’erreur de prendre le relais sans persister le texte corrompu dans la session.

Si cela se produit à répétition, capturez le nom brut du modèle, le fichier de session actuel et indiquez 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 "Reply with exactly: ok" --jsonopenclaw models set ollama/gemma4

Les grands modèles locaux peuvent nécessiter un long premier chargement avant que le streaming ne commence. Gardez le délai d’expiration limité au fournisseur Ollama, et demandez éventuellement à Ollama de garder 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 aussi le délai d’expiration de connexion Undici protégé pour ce fournisseur.

De nombreux modèles Ollama annoncent des contextes plus grands que ce que votre matériel peut exécuter confortablement. Ollama natif utilise le contexte d’exécution par défaut propre à Ollama, sauf si vous définissez params.num_ctx. Limitez à la fois le budget d’OpenClaw et le contexte de requête d’Ollama lorsque vous voulez une latence prévisible jusqu’au 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 d’abord contextWindow si OpenClaw envoie une invite trop longue. Réduisez params.num_ctx si Ollama charge un contexte d’exécution trop grand pour la machine. Réduisez maxTokens si la génération dure trop longtemps.