◆ Agents Locaux — Des agents qui agissent sur ta machine, sans cloud · 24 € · ou tous les kits 49 € →

#OpenClaw et Ollama : qui fait quoi

OpenClaw est une passerelle : un processus qui reçoit vos messages depuis une messagerie, les transmet à un modèle de langage et exécute les actions que ce modèle demande. Ollama est un serveur de modèles : il charge un modèle en mémoire et répond sur le port 11434 de la machine, à l'adresse http://localhost:11434 par défaut. Brancher l'un sur l'autre revient à déclarer Ollama comme fournisseur dans OpenClaw, puis à désigner un modèle local comme modèle principal de l'agent.

D'après la documentation d'OpenClaw, cette liaison passe par l'API native d'Ollama (le point d'accès /api/chat), qui prend en charge la réponse en flux continu et l'appel d'outils. Ce détail compte plus qu'il n'en a l'air : on verra qu'une adresse mal écrite suffit à faire basculer la passerelle sur un autre mode, où les outils ne fonctionnent plus.

Ollama: Charge le modèle, lui alloue une fenêtre de contexte et génère le texte. C'est lui qui décide de la mémoire consommée.
OpenClaw: Envoie à chaque tour la consigne système, la description des outils disponibles et l'historique de la conversation, puis exécute les outils que le modèle demande.
Le modèle: Doit garder en tête une longue consigne et savoir demander un outil dans le format attendu. Tous les modèles locaux n'en sont pas capables.
Ce qui ne change pas: Les messageries, la mémoire de l'assistant, le jeton et la sécurité de la passerelle restent réglés côté OpenClaw, quel que soit le fournisseur du modèle.

Ce branchement est plus délicat que celui d'une interface de discussion. Un chat envoie quelques lignes au modèle ; un agent lui envoie d'emblée plusieurs milliers de tokens de consignes et de définitions d'outils, avant même votre premier message. Les réglages par défaut d'Ollama sont pensés pour le premier cas, pas pour le second.

Local ne veut pas dire sans risque

Un modèle local évite d'envoyer vos conversations à un fournisseur en ligne. Il ne retire rien aux risques propres à un agent : OpenClaw lit des contenus venus de l'extérieur et peut exécuter des commandes. Un petit modèle se laisse en général plus facilement détourner par un texte piégé qu'un grand, et la documentation de sécurité du projet invite à la prudence sur ce point. Gardez la passerelle sur une machine dédiée, avec le moins d'outils possible, et relancez openclaw security audit --deep après avoir changé de modèle.

#Prérequis

Le kit Agents Locaux

Des agents qui agissent sur ta machine : Cline agentique, MCP, n8n + Ollama, automatisations locales.

Espace en ligne à vie
PDF + fichiers
Remboursé 30 j

Le kit Agents Locaux →ou tous les kits à vie — 49 € →

OpenClaw installé: Une passerelle qui démarre et dont le diagnostic passe. L'installation n'est pas reprise ici : voir notre guide « Installer OpenClaw avec Docker ».
Ollama installé et à jour: La commande ollama launch utilisée plus bas n'existe que dans les versions récentes. L'installation est traitée dans notre guide « Installer Ollama ».
De la mémoire pour le modèle et son contexte: Repères en Q4_K_M pour les seuls poids : environ 5 Go pour un modèle de 7 milliards de paramètres, 9 Go pour 14 milliards, 19 Go pour 32 milliards. La fenêtre de contexte demandée par un agent s'ajoute à ce chiffre.
Un accès au terminal: Sur la machine qui héberge la passerelle, et sur celle qui héberge Ollama si ce n'est pas la même.

Terminal — vérifier les deux outils

ollama --version
openclaw --version

# Le serveur Ollama répond-il ?
curl http://localhost:11434/api/tags

La dernière commande doit renvoyer la liste des modèles installés, au format JSON. Une connexion refusée signifie qu'Ollama n'est pas démarré : lancez l'application, ou ollama serve dans un terminal. Inutile d'aller plus loin tant que cette réponse n'arrive pas.

#Étape 1 : prévoir 64 000 tokens de contexte

C'est le réglage qui fait échouer le plus d'installations, et il se fait côté Ollama, pas côté OpenClaw. La page qu'Ollama consacre à OpenClaw indique que l'assistant a besoin d'une grande fenêtre de contexte et recommande au moins 64 000 tokens avec un modèle local. Sa page sur la longueur de contexte donne la même valeur pour les agents, la recherche web et les outils de code.

Or Ollama choisit sa fenêtre par défaut selon la mémoire vidéo disponible : d'après cette même documentation, 4 000 tokens environ sous 24 Gio de VRAM, 32 000 entre 24 et 48 Gio, 256 000 à partir de 48 Gio. Sur une carte de 12 ou 16 Go, le serveur démarre donc avec une fenêtre seize fois plus petite que la recommandation. Rien ne le signale : Ollama tronque ce qui dépasse, sans message d'erreur.

Terminal — Ollama lancé à la main (Linux, macOS)

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Si Ollama tourne déjà comme application (macOS, Windows), ne lancez pas cette commande : un second serveur entrerait en conflit sur le port 11434. Réglez la longueur de contexte dans les paramètres de l'application. Sous Linux, quand Ollama a été installé comme service systemd, la variable se déclare dans le service lui-même.

Terminal — Ollama installé comme service (Linux)

sudo systemctl edit ollama.service

# Dans l'éditeur qui s'ouvre, ajouter ces deux lignes :
# [Service]
# Environment="OLLAMA_CONTEXT_LENGTH=64000"

sudo systemctl daemon-reload
sudo systemctl restart ollama

64 000 tokens se paient en mémoire

La fenêtre de contexte réserve de la mémoire en plus des poids du modèle. Un modèle qui tient à l'aise en discussion peut déborder vers le processeur une fois le contexte relevé, et l'agent devient alors très lent. Nous ne donnons pas de chiffre, car il dépend du modèle : la commande ollama ps, vue à l'étape 4, montre ce qui est réellement alloué. Si cela déborde, prenez un modèle plus petit plutôt que de raboter le contexte. Deux variables documentées dans la FAQ d'Ollama réduisent la facture : OLLAMA_FLASH_ATTENTION=1 et OLLAMA_KV_CACHE_TYPE=q8_0.

#Étape 2 : choisir un modèle qui sait appeler des outils

Un agent n'agit que par ses outils : lire un fichier, lancer une commande, chercher sur le web. Un modèle qui ne sait pas formuler une demande d'outil répondra poliment à vos messages, mais ne fera jamais rien. Cette page ne classe pas les modèles ; elle donne les critères à vérifier avant d'en brancher un.

La capacité « tools »: La commande ollama show affiche une rubrique Capabilities. Elle doit contenir tools. Dans la bibliothèque d'Ollama, le filtre correspondant se trouve à l'adresse https://ollama.com/search?c=tools.
Une fenêtre native suffisante: La même commande affiche la longueur de contexte maximale du modèle. Un modèle conçu pour 8 000 ou 32 000 tokens ne pourra pas suivre la recommandation de 64 000, quel que soit le réglage du serveur.
Un budget mémoire réaliste: Poids et contexte doivent tenir ensemble dans la VRAM, ou dans la mémoire unifiée d'un Mac. Sur une carte de 12 Go (RTX 3060, RTX 4070), cela oriente vers des modèles nettement plus petits que ceux que la carte accepte en simple discussion ; 16 Go (RTX 4080) et 24 Go (RTX 4090) laissent plus de marge.
La tenue sur la durée: Un agent enchaîne plusieurs appels d'outils par demande. Les très petits modèles se trompent plus souvent de format ou d'outil. Aucune fiche ne remplace un essai sur vos propres demandes, à faible enjeu d'abord.

Terminal — télécharger puis inspecter un modèle

ollama pull gpt-oss:20b
ollama show gpt-oss:20b

Le nom gpt-oss:20b sert d'exemple dans la suite de ce guide : remplacez-le par le modèle que vous avez retenu. La page d'intégration d'Ollama tient à jour une liste de modèles suggérés pour OpenClaw, qui change au fil des sorties ; mieux vaut s'y reporter que se fier à une liste figée ici.

Un modèle « cloud » n'est pas un modèle local

La bibliothèque d'Ollama et le sélecteur de la commande ollama launch proposent aussi des modèles dont l'étiquette se termine par cloud. Ils s'exécutent sur les serveurs d'Ollama, pas sur votre machine : vos messages sortent de chez vous. Pour une installation réellement locale, choisissez un modèle téléchargé, visible dans ollama list.

#Étape 3 : configurer le fournisseur Ollama dans OpenClaw

Deux voies existent. La première est une commande d'Ollama qui écrit la configuration à votre place. La seconde consiste à déclarer le fournisseur soi-même dans la configuration d'OpenClaw ; elle est indispensable dès que la passerelle tourne dans Docker ou qu'Ollama se trouve sur une autre machine.

#Voie rapide : ollama launch openclaw

Terminal

# Configurer OpenClaw pour Ollama et démarrer la passerelle
ollama launch openclaw

# Configurer sans rien lancer
ollama launch openclaw --config

D'après la documentation d'Ollama, cette commande fait choisir un modèle, configure OpenClaw pour utiliser Ollama et démarre la passerelle ; si celle-ci tourne déjà, elle recharge la nouvelle configuration d'elle-même. L'ancien nom du projet reste accepté : ollama launch clawdbot est un alias. La commande s'adresse à un OpenClaw installé directement sur la machine, avec la commande openclaw disponible dans le terminal. Elle ne dispense pas de l'étape 1 : la même page demande de relever le contexte du serveur.

#Voie manuelle : déclarer le fournisseur soi-même

La documentation d'OpenClaw décrit d'abord un mode de découverte automatique. On fournit une clé factice, puisque Ollama n'en demande aucune, et OpenClaw interroge l'instance locale à l'adresse http://127.0.0.1:11434 pour y trouver les modèles installés.

Terminal — activer le fournisseur et choisir le modèle

# N'importe quelle valeur convient : Ollama ne vérifie pas de clé
export OLLAMA_API_KEY="ollama-local"

# Ou l'inscrire dans la configuration d'OpenClaw
openclaw config set models.providers.ollama.apiKey "ollama-local"

# Lister les modèles vus par OpenClaw, puis fixer le modèle principal
openclaw models list
openclaw models set ollama/gpt-oss:20b

Un modèle se désigne sous la forme ollama/ suivie du nom exact affiché par ollama list, étiquette comprise. Préférez l'inscription dans la configuration à la variable d'environnement quand la passerelle tourne comme service : une variable exportée dans votre terminal n'est pas transmise à un processus démarré par le système. Avec une installation Docker, chaque commande openclaw se préfixe par docker compose run --rm openclaw-cli.

Le second mode est la déclaration explicite, dans le fichier ~/.openclaw/openclaw.json, écrit en JSON5. Il sert quand Ollama tourne ailleurs que sur la machine de la passerelle, quand un modèle n'apparaît pas dans la liste, ou quand vous voulez fixer vous-même la fenêtre annoncée à l'agent.

~/.openclaw/openclaw.json — déclaration explicite (JSON5)

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        models: [
          {
            id: "gpt-oss:20b",
            name: "GPT-OSS 20B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 64000,
            maxTokens: 8192
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: { primary: "ollama/gpt-oss:20b" }
    }
  }
}

baseUrl: L'adresse du serveur Ollama, port compris, sans rien après. C'est la seule ligne à changer quand Ollama tourne sur une autre machine.
api: "ollama": Demande explicitement l'API native d'Ollama, celle qui gère l'appel d'outils.
apiKey: Une valeur factice. Elle sert seulement à activer le fournisseur.
contextWindow: La fenêtre annoncée à OpenClaw, qui s'en sert pour gérer la longueur de l'historique. Elle doit correspondre à ce qu'Ollama charge réellement, pas à ce que le modèle accepterait en théorie.
maxTokens: Le plafond de longueur d'une réponse.
cost: Des zéros : un modèle local n'est pas facturé au token.
agents.defaults.model.primary: Le modèle utilisé par défaut par l'agent, sous la forme ollama/nom-du-modèle.

Cet exemple reprend la structure donnée par la documentation d'OpenClaw ; les valeurs de contextWindow et de maxTokens sont les nôtres, à ajuster à votre modèle. Deux choses à retenir. D'abord, passez reasoning à true pour un modèle à réflexion. Ensuite, d'après la même documentation, la découverte automatique est désactivée dès qu'une entrée models.providers.ollama explicite existe : chaque modèle que vous voulez utiliser doit alors figurer dans la liste models.

Pas de /v1 à la fin de l'adresse

Beaucoup d'outils se branchent sur Ollama par son interface compatible OpenAI, à l'adresse http://localhost:11434/v1. La documentation d'OpenClaw demande explicitement de ne pas l'utiliser : dans ce mode, l'appel d'outils n'est plus fiable et le modèle peut renvoyer le JSON de l'outil sous forme de texte brut. L'adresse correcte s'arrête au port : http://localhost:11434.

Terminal — appliquer et contrôler

openclaw gateway restart
openclaw doctor

#Passerelle dans Docker ou Ollama sur une autre machine

À l'intérieur d'un conteneur, localhost désigne le conteneur lui-même. Une passerelle OpenClaw lancée avec Docker ne voit donc pas l'Ollama de la machine hôte à l'adresse http://localhost:11434 : la connexion est refusée alors que tout fonctionne depuis votre terminal. La solution dépend de l'endroit où Ollama tourne.

Docker Desktop (macOS, Windows): Le nom host.docker.internal désigne la machine hôte depuis le conteneur. Indiquez http://host.docker.internal:11434 comme baseUrl dans la déclaration explicite.
Docker Engine sous Linux: Ce nom n'existe pas par défaut : il faut l'ajouter au service avec extra_hosts, comme ci-dessous. Ollama doit en plus écouter sur une interface que le conteneur peut joindre, ce qui n'est pas le cas de son réglage d'origine, limité à la boucle locale.
Ollama sur une autre machine: Mettez l'adresse de cette machine sur votre réseau local ou votre VPN dans baseUrl, et réglez de même l'écoute d'Ollama sur cette machine.

docker-compose.override.yml — exemple à adapter (Linux)

services:
  openclaw-gateway:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Terminal — faire écouter Ollama au-delà de la boucle locale (service Linux)

sudo systemctl edit ollama.service

# Dans l'éditeur qui s'ouvre, ajouter ces deux lignes :
# [Service]
# Environment="OLLAMA_HOST=0.0.0.0:11434"

sudo systemctl daemon-reload
sudo systemctl restart ollama

Le fichier Compose est un exemple de notre part, pas un extrait de la documentation d'OpenClaw : comparez le nom du service avec le docker-compose.yml de votre version. La variable OLLAMA_HOST, elle, est décrite dans la FAQ d'Ollama. Mesurez ce qu'elle implique : avec 0.0.0.0, le serveur écoute sur toutes les interfaces de la machine, et l'API d'Ollama ne demande aucune authentification. Un pare-feu doit limiter le port 11434 au réseau Docker ou au réseau local, et ce port ne doit jamais être joignable depuis Internet. Notre guide sur la sécurisation d'un serveur Ollama détaille ces règles.

#Étape 4 : vérifier la liaison de bout en bout

Un agent qui répond « bonjour » ne prouve rien : cette réponse ne demande ni outil ni contexte. La vérification utile avance couche par couche, du serveur de modèles jusqu'à la messagerie.

01
Tester l'appel d'outils sur Ollama seul
Envoyez au serveur une question accompagnée d'un outil fictif, avec la commande ci-dessous. La réponse doit contenir un champ tool_calls qui nomme l'outil et lui passe un argument. Si le modèle répond par une phrase, il ne convient pas à un agent.
02
Contrôler ce que voit OpenClaw
La commande openclaw models list doit afficher votre modèle sous la forme ollama/nom-du-modèle, et openclaw doctor ne doit pas signaler d'erreur de fournisseur.
03
Demander une action, pas une réponse
Depuis l'interface de contrôle ou votre messagerie, envoyez une demande qui oblige l'agent à se servir d'un outil, par exemple lister les fichiers de son espace de travail. Il doit le faire réellement, pas décrire ce qu'il ferait.
04
Regarder ce qu'Ollama a chargé
Juste après cet échange, lancez ollama ps sur la machine du serveur et lisez les colonnes CONTEXT et PROCESSOR.

Terminal — 1. un appel d'outils directement sur Ollama

curl http://localhost:11434/api/chat -d '{
  "model": "gpt-oss:20b",
  "stream": false,
  "messages": [{"role": "user", "content": "Quel temps fait-il à Lyon ?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Donne la météo actuelle pour une ville",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}'

Terminal — 2 et 4. côté OpenClaw, puis côté Ollama

openclaw models list
openclaw doctor

# Après un échange avec l'agent
ollama ps

Dans la sortie d'ollama ps, la colonne CONTEXT donne la fenêtre réellement allouée au modèle chargé. Si elle affiche 4096 alors que vous visiez 64 000, le réglage de l'étape 1 n'a pas été pris en compte, quoi qu'indique la configuration d'OpenClaw. La colonne PROCESSOR donne la répartition entre carte graphique et processeur : la mention 100% GPU est celle que l'on cherche ; une répartition mixte signale que le modèle et son contexte débordent de la mémoire vidéo.

→

Isoler la couche fautive

Si le test direct sur Ollama (le premier des quatre contrôles) échoue, le problème vient du modèle ou d'Ollama, et aucun réglage d'OpenClaw ne le corrigera. S'il réussit mais que l'agent n'agit pas, cherchez du côté de la liaison : adresse du serveur, mode d'API, fenêtre de contexte. Ce tri évite de modifier la configuration au hasard.

#Pannes silencieuses : les symptômes et leurs causes

Les erreurs franches (connexion refusée, modèle introuvable) se lisent dans les journaux. Les pannes ci-dessous sont plus coûteuses, parce que l'assistant continue de répondre : il répond seulement mal.

L'assistant ignore ses consignes ou répond à côté: Cause la plus probable : le contexte est tronqué. La consigne système et les définitions d'outils dépassent la fenêtre chargée par Ollama, qui en coupe une partie sans prévenir. Vérifiez la colonne CONTEXT d'ollama ps et reprenez l'étape 1.
Du JSON s'affiche à la place de l'action: Le modèle a bien formulé un appel d'outil, mais la passerelle l'a reçu comme du texte. C'est le signe d'une adresse en /v1 ou d'un fournisseur déclaré en mode compatible OpenAI. Revenez à l'adresse native et à api: "ollama".
Il décrit ce qu'il ferait, sans rien faire: Le modèle ne déclare pas la capacité tools, ou il est trop limité pour l'utiliser au milieu d'une longue consigne. Refaites le test direct sur Ollama décrit à l'étape 4 ; s'il échoue, changez de modèle.
Le modèle n'apparaît pas dans openclaw models list: Trois pistes. Le fournisseur n'est pas activé (clé factice absente, ou variable non transmise au service). Une entrée models.providers.ollama explicite existe et ne liste pas ce modèle. Ou le modèle ne déclare pas l'appel d'outils : d'après la documentation que nous connaissons, la découverte automatique ne retient que ceux qui le déclarent, un comportement qui a pu évoluer selon les versions.
Le réglage du contexte reste sans effet: La variable OLLAMA_CONTEXT_LENGTH a été exportée dans un terminal alors qu'Ollama tourne comme service ou comme application : le serveur ne l'a jamais vue. Déclarez-la dans le service, ou dans les paramètres de l'application, puis redémarrez Ollama.
Les réponses mettent très longtemps, ou n'arrivent pas: Soit le modèle déborde sur le processeur (colonne PROCESSOR d'ollama ps), soit il a été déchargé après une période d'inactivité et se recharge à chaque message : par défaut, Ollama garde un modèle en mémoire cinq minutes. La variable OLLAMA_KEEP_ALIVE allonge ce délai.
Tout marche au terminal, rien depuis la passerelle: La passerelle tourne dans un conteneur et cherche Ollama sur son propre localhost. Voir la section sur Docker.
« Model context window too small »: Celle-ci n'est pas silencieuse, mais elle déroute : les versions d'OpenClaw que nous connaissons refusent un modèle dont la fenêtre annoncée est trop petite. Relevez contextWindow dans la déclaration explicite, et le contexte d'Ollama en conséquence.

Terminal — suivre les journaux des deux côtés

# Passerelle OpenClaw
openclaw logs --follow

# Serveur Ollama installé comme service (Linux)
journalctl -u ollama -f

Une limite à garder en tête une fois la liaison établie : un modèle local correctement branché ne se comportera pas forcément comme un grand modèle en ligne sur des tâches longues ou ambiguës. Nous ne publions ici aucun comparatif ni aucun débit. Commencez par des demandes simples et sans enjeu, observez où le modèle décroche, et gardez un fournisseur en ligne en modèle de secours si l'assistant vous sert au quotidien.

#Sources officielles à garder sous la main

Ce guide ne repose sur aucun test maison : il ne contient ni durée, ni débit, ni score. Les commandes et les noms de champs reprennent la documentation des deux projets, qui change d'une version à l'autre : options d'ollama launch, comportement de la découverte automatique, valeurs par défaut. En cas d'écart entre cette page et la documentation, c'est la documentation qui fait foi.

Ollama : intégration OpenClaw

https://docs.ollama.com/integrations/openclaw

OpenClaw : fournisseur Ollama

https://docs.openclaw.ai/providers/ollama

Ollama : longueur de contexte

https://docs.ollama.com/context-length

Ollama : FAQ (variables du serveur)

https://docs.ollama.com/faq

OpenClaw : sécurité de la passerelle

https://docs.openclaw.ai/gateway/security

#Pour aller plus loin

Le branchement repose sur trois notions traitées en détail ailleurs sur le site : le serveur Ollama, la fenêtre de contexte et l'appel d'outils.

Installer Ollama: L'installation du serveur de modèles, ses réglages de base et ce qui peut sortir de la machine. https://quelllm.fr/guide/installer-ollama
Comprendre la fenêtre de contexte: Ce que mesure un token, pourquoi le contexte consomme de la mémoire et comment le dimensionner. https://quelllm.fr/guide/comprendre-fenetre-contexte
L'appel d'outils avec Ollama: Le format des demandes d'outils et la façon de les tester hors de tout agent. https://quelllm.fr/guide/appel-outil-ollama-tutoriel
Hermes Agent avec Ollama: Un autre agent auto-hébergé branché sur un modèle local, pour comparer les approches. https://quelllm.fr/guide/hermes-agent-ollama-guide
Installer OpenClaw avec Docker: L'installation de la passerelle, sa mise à jour et les règles d'exposition sur un VPS. https://quelllm.fr/guide/installer-openclaw-docker

Ce guide vous a aidé ?

Un retour, une erreur, une précision ? Faites-nous signe, ça améliore le guide pour tout le monde.

Les kits QuelLLMLe guide de référence par usage

Agents Locaux Copilote Local IA Locale RAG Local IA en Entreprise IA Sans Filtre Mac Images IA

Tous les kits à vie — 49 €