◆ Agentes Locales — Agentes que actúan en tu máquina, sin nube · 24 € · o todos los kits 49 € →

#OpenClaw y Ollama: quién hace qué

OpenClaw es una pasarela: un proceso que recibe tus mensajes desde una aplicación de mensajería, los transmite a un modelo de lenguaje y ejecuta las acciones que este modelo solicita. Ollama es un servidor de modelos: carga un modelo en memoria y responde en el puerto 11434 de la máquina, en la dirección http://localhost:11434 de forma predeterminada. Conectar uno con el otro consiste en declarar Ollama como proveedor en OpenClaw y designar después un modelo local como modelo principal del agente.

Según la documentación de OpenClaw, esta conexión pasa por la API nativa de Ollama (el punto de acceso /api/chat), que admite respuestas en streaming y llamadas a herramientas. Este detalle importa más de lo que parece: veremos que una dirección mal escrita basta para hacer que la pasarela cambie a otro modo, en el que las herramientas dejan de funcionar.

Ollama: Carga el modelo, le asigna una ventana de contexto y genera el texto. Es él quien decide cuánta memoria consume.
OpenClaw: Envía en cada turno la instrucción del sistema, la descripción de las herramientas disponibles y el historial de la conversación; después ejecuta las herramientas que solicita el modelo.
El modelo: Debe mantener en mente una instrucción larga y saber solicitar una herramienta en el formato esperado. No todos los modelos locales son capaces de hacerlo.
Lo que no cambia: Las mensajerías, la memoria del asistente, el token y la seguridad de la pasarela siguen configurándose desde OpenClaw, independientemente del proveedor del modelo.

Esta conexión es más delicada que la de una interfaz de conversación. Un chat envía unas pocas líneas al modelo; un agente le envía de entrada varios miles de tokens de instrucciones y definiciones de herramientas, incluso antes de tu primer mensaje. Los ajustes predeterminados de Ollama están pensados para el primer caso, no para el segundo.

Local no significa sin riesgos

Un modelo local evita enviar tus conversaciones a un proveedor en línea. No elimina ninguno de los riesgos propios de un agente: OpenClaw lee contenidos procedentes del exterior y puede ejecutar comandos. Por lo general, un modelo pequeño se deja manipular más fácilmente mediante un texto malicioso que uno grande, y la documentación de seguridad del proyecto invita a extremar la prudencia en este punto. Mantén la pasarela en una máquina dedicada, con el menor número posible de herramientas, y vuelve a ejecutar openclaw security audit --deep después de cambiar de modelo.

#Prerrequisitos

El kit de Agentes Locales

Agentes que actúan en tu máquina: Cline agéntico, MCP, n8n + Ollama, automatizaciones locales.

Espacio en línea de por vida
PDF + archivos
Actualizaciones de por vida

El kit Agentes Locales →o todos los kits de por vida — 49 € →

OpenClaw instalado: Una pasarela que arranca y cuyo diagnóstico es correcto. La instalación no se trata aquí: consulta nuestra guía « Instalar OpenClaw con Docker ».
Ollama instalado y actualizado: El comando ollama launch utilizado más abajo solo existe en las versiones recientes. La instalación se trata en nuestra guía «Instalar Ollama».
Memoria para el modelo y su contexto: Referencias en Q4_K_M solo para los pesos: aproximadamente 5 GB para un modelo de 7 mil millones de parámetros, 9 GB para 14 mil millones y 19 GB para 32 mil millones. La ventana de contexto solicitada por un agente se suma a esta cifra.
Acceso al terminal: En la máquina que aloja la pasarela y en la que aloja Ollama si no es la misma.

Terminal — comprobar las dos herramientas

ollama --version
openclaw --version

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

El último comando debe devolver la lista de modelos instalados en formato JSON. Una conexión rechazada significa que Ollama no se ha iniciado: inicia la aplicación o ejecuta ollama serve en un terminal. No tiene sentido seguir mientras no llegue esta respuesta.

#Paso 1: prever 64 000 tokens de contexto

Es el ajuste que hace fallar a más instalaciones y se realiza en Ollama, no en OpenClaw. La página que Ollama dedica a OpenClaw indica que el asistente necesita una ventana de contexto grande y recomienda al menos 64 000 tokens con un modelo local. Su página sobre la longitud del contexto proporciona el mismo valor para los agentes, la búsqueda web y las herramientas de código.

Pero Ollama elige su ventana predeterminada según la memoria de vídeo disponible: según esa misma documentación, unos 4 000 tokens con menos de 24 GiB de VRAM, 32 000 entre 24 y 48 GiB, y 256 000 a partir de 48 GiB. En una tarjeta de 12 o 16 GB, el servidor se inicia, por tanto, con una ventana dieciséis veces más pequeña que la recomendada. Nada lo indica: Ollama trunca lo que sobra, sin mostrar ningún mensaje de error.

Terminal — Ollama iniciado manualmente (Linux, macOS)

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Si Ollama ya se ejecuta como aplicación (macOS, Windows), no ejecutes este comando: un segundo servidor entraría en conflicto en el puerto 11434. Ajusta la longitud del contexto en la configuración de la aplicación. En Linux, cuando Ollama se ha instalado como servicio systemd, la variable se declara en el propio servicio.

Terminal — Ollama instalado como servicio (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 pagan en memoria

La ventana de contexto reserva memoria adicional a la de los pesos del modelo. Un modelo que funciona cómodamente en una conversación puede desbordarse hacia el procesador cuando se aumenta el contexto, y el agente se vuelve entonces muy lento. No damos una cifra porque depende del modelo: el comando ollama ps, que se muestra en el paso 4, indica lo que se ha asignado realmente. Si se desborda, elija un modelo más pequeño en lugar de recortar el contexto. Dos variables documentadas en las preguntas frecuentes de Ollama reducen el consumo: OLLAMA_FLASH_ATTENTION=1 y OLLAMA_KV_CACHE_TYPE=q8_0.

#Paso 2: elegir un modelo que sepa llamar a herramientas

Un agente solo actúa mediante sus herramientas: leer un archivo, ejecutar un comando, buscar en la web. Un modelo que no sabe formular una solicitud de herramienta responderá amablemente a sus mensajes, pero nunca hará nada. Esta página no clasifica los modelos; ofrece los criterios que debe comprobar antes de conectar uno.

La capacidad de «tools»: El comando ollama show affiche incluye una sección Capabilities. Debe contener tools. En la biblioteca de Ollama, el filtro correspondiente se encuentra en la dirección https://ollama.com/search?c=tools.
Una ventana nativa suficiente: El mismo comando muestra la longitud máxima de contexto del modelo. Un modelo diseñado para 8 000 o 32 000 tokens no podrá seguir la recomendación de 64 000, independientemente del ajuste del servidor.
Un presupuesto de memoria realista: El peso y el contexto deben caber juntos en la VRAM o en la memoria unificada de un Mac. En una tarjeta de 12 GB (RTX 3060, RTX 4070), esto orienta hacia modelos claramente más pequeños que los que la tarjeta admite para una simple conversación; 16 GB (RTX 4080) y 24 GB (RTX 4090) dejan más margen.
El rendimiento sostenido: Un agente encadena varias llamadas a herramientas por solicitud. Los modelos muy pequeños se equivocan más a menudo de formato o de herramienta. Ninguna ficha sustituye una prueba con sus propias solicitudes, empezando por las de bajo riesgo.

Terminal — descargar y después inspeccionar un modelo

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

El nombre gpt-oss:20b sirve de ejemplo en el resto de esta guía: sustitúyelo por el modelo que hayas elegido. La página de integración de Ollama mantiene actualizada una lista de modelos sugeridos para OpenClaw, que cambia a medida que aparecen nuevas versiones; es mejor consultarla que fiarse de una lista fija aquí.

Un modelo « cloud » no es un modelo local

La biblioteca de Ollama y el selector del comando ollama launch también ofrecen modelos cuya etiqueta termina en cloud. Se ejecutan en los servidores de Ollama, no en tu máquina: tus mensajes salen de tu equipo. Para una instalación realmente local, elige un modelo descargado, visible en ollama list.

#Paso 3: configurar el proveedor Ollama en OpenClaw

Existen dos vías. La primera es un comando de Ollama que escribe la configuración por ti. La segunda consiste en declarar el proveedor manualmente en la configuración de OpenClaw; es indispensable cuando la pasarela se ejecuta en Docker o cuando Ollama se encuentra en otra máquina.

#Vía rápida: ollama launch openclaw

Terminal

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

# Configurer sans rien lancer
ollama launch openclaw --config

Según la documentación de Ollama, este comando permite elegir un modelo, configura OpenClaw para utilizar Ollama e inicia la pasarela; si esta ya está en funcionamiento, recarga por sí sola la nueva configuración. El nombre antiguo del proyecto sigue siendo válido: ollama launch clawdbot es un alias. El comando está dirigido a un OpenClaw instalado directamente en la máquina, con el comando openclaw disponible en la terminal. No exime del paso 1: la misma página pide anotar el contexto del servidor.

#Vía manual: declarar el proveedor por cuenta propia

La documentación de OpenClaw describe primero un modo de descubrimiento automático. Proporcionamos una clave ficticia, ya que Ollama no requiere ninguna, y OpenClaw consulta la instancia local en la dirección http://127.0.0.1:11434 para encontrar los modelos instalados.

Terminal — activar el proveedor y elegir el modelo

# 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 modelo se indica con la forma ollama/ seguida del nombre exacto que muestra ollama list, incluida la etiqueta. Prefiera especificarlo en la configuración en lugar de usar la variable de entorno cuando la pasarela se ejecuta como servicio: una variable exportada en el terminal no se transmite a un proceso iniciado por el sistema. Con una instalación de Docker, cada comando openclaw lleva como prefijo docker compose run --rm openclaw-cli.

El segundo modo consiste en declarar explícitamente el proveedor en el archivo ~/.openclaw/openclaw.json, escrito en JSON5. Se utiliza cuando Ollama se ejecuta en otro lugar distinto de la máquina de la pasarela, cuando un modelo no aparece en la lista o cuando usted quiere fijar la ventana anunciada al agente.

~/.openclaw/openclaw.json — declaración explícita (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: La dirección del servidor Ollama, incluido el puerto, sin nada después. Es la única línea que debes cambiar cuando Ollama se ejecuta en otra máquina.
api: "ollama": Solicita explícitamente la API nativa de Ollama, la que gestiona la llamada a herramientas.
apiKey: Un valor ficticio. Solo sirve para activar el proveedor.
contextWindow: La ventana anunciada a OpenClaw, que la utiliza para gestionar la longitud del historial. Debe corresponderse con lo que Ollama carga realmente, no con lo que el modelo aceptaría en teoría.
maxTokens: El límite de longitud de una respuesta.
cost: Cero: un modelo local no se factura por token.
agents.defaults.model.primary: El modelo utilizado por defecto por el agente, en la forma ollama/nombre-del-modelo.

Este ejemplo retoma la estructura proporcionada por la documentación de OpenClaw; los valores de contextWindow y maxTokens son los nuestros y deben ajustarse a tu modelo. Hay dos cosas que recordar. Primero, establece reasoning en true para un modelo con capacidad de razonamiento. Después, según la misma documentación, el descubrimiento automático se desactiva en cuanto existe una entrada models.providers.ollama explícita: cada modelo que quieras utilizar debe aparecer entonces en la lista models.

No pongas /v1 al final de la dirección

Muchas herramientas se conectan a Ollama mediante su interfaz compatible con OpenAI, en la dirección http://localhost:11434/v1. La documentación de OpenClaw pide explícitamente no utilizarla: en este modo, la llamada a herramientas deja de ser fiable y el modelo puede devolver el JSON de la herramienta como texto sin formato. La dirección correcta termina en el puerto: http://localhost:11434.

Terminal — aplicar y comprobar

openclaw gateway restart
openclaw doctor

#Pasarela en Docker o Ollama en otra máquina

Dentro de un contenedor, localhost designa al propio contenedor. Por tanto, una pasarela OpenClaw iniciada con Docker no ve el Ollama de la máquina anfitriona en la dirección http://localhost:11434: la conexión se rechaza aunque todo funcione desde el terminal. La solución depende del lugar donde se ejecute Ollama.

Docker Desktop (macOS, Windows): El nombre host.docker.internal designa la máquina anfitriona desde el contenedor. Indica http://host.docker.internal:11434 como baseUrl en la declaración explícita.
Docker Engine en Linux: Este nombre no existe de forma predeterminada: hay que añadirlo al servicio con extra_hosts, como se muestra a continuación. Además, Ollama debe escuchar en una interfaz a la que el contenedor pueda conectarse, algo que no ocurre con su configuración original, limitada al bucle local.
Ollama en otra máquina: Pon la dirección de esta máquina en tu red local o VPN en baseUrl y configura del mismo modo la escucha de Ollama en esta máquina.

docker-compose.override.yml — ejemplo que debe adaptarse (Linux)

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

Terminal — hacer que Ollama escuche más allá del bucle local (servicio 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

El archivo Compose es un ejemplo nuestro, no un fragmento de la documentación de OpenClaw: compara el nombre del servicio con el docker-compose.yml de tu versión. La variable OLLAMA_HOST, en cambio, está descrita en las preguntas frecuentes de Ollama. Mide lo que implica: con 0.0.0.0, el servidor escucha en todas las interfaces de la máquina, y la API de Ollama no solicita ninguna autenticación. Un cortafuegos debe limitar el puerto 11434 a la red de Docker o a la red local, y este puerto nunca debe ser accesible desde Internet. Nuestra guía sobre la protección de un servidor Ollama detalla estas reglas.

#Paso 4: comprobar la conexión de extremo a extremo

Un agente que responde «hola» no demuestra nada: esa respuesta no requiere ni herramientas ni contexto. La verificación útil avanza capa por capa, desde el servidor de modelos hasta la mensajería.

01
Probar la llamada a herramientas solo en Ollama
Envía al servidor una pregunta acompañada de una herramienta ficticia, con el comando siguiente. La respuesta debe contener un campo tool_calls que nombre la herramienta y le pase un argumento. Si el modelo responde con una frase, no es adecuado para un agente.
02
Controlar lo que ve OpenClaw
El comando openclaw models list debe mostrar tu modelo con el formato ollama/nombre-del-modelo, y openclaw doctor no debe señalar ningún error del proveedor.
03
Pedir una acción, no una respuesta
Desde la interfaz de control o tu mensajería, envía una solicitud que obligue al agente a utilizar una herramienta, por ejemplo, enumerar los archivos de su espacio de trabajo. Debe hacerlo realmente, no describir lo que haría.
04
Ver lo que ha cargado Ollama
Justo después de este intercambio, ejecuta ollama ps en la máquina del servidor y lee las columnas CONTEXT y PROCESSOR.

Terminal — 1. una llamada a herramientas directamente en 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 y 4. en el lado de OpenClaw y después en el de Ollama

openclaw models list
openclaw doctor

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

En la salida de ollama ps, la columna CONTEXT indica la ventana asignada realmente al modelo cargado. Si muestra 4096 cuando se esperaba 64 000, la configuración del paso 1 no se ha aplicado, independientemente de lo que indique la configuración de OpenClaw. La columna PROCESSOR muestra el reparto entre la tarjeta gráfica y el procesador: la indicación 100% GPU es la que buscamos; un reparto mixto señala que el modelo y su contexto desbordan la memoria de vídeo.

→

Aislar la capa defectuosa

Si falla la prueba directa en Ollama (la primera de las cuatro comprobaciones), el problema procede del modelo o de Ollama, y ningún ajuste de OpenClaw lo solucionará. Si tiene éxito pero el agente no actúa, busca el problema en la conexión: dirección del servidor, modo de API, ventana de contexto. Esta clasificación evita modificar la configuración al azar.

#Fallos silenciosos: los síntomas y sus causas

Los errores claros (conexión rechazada, modelo no encontrado) se ven en los registros. Los fallos que aparecen a continuación son más costosos, porque el asistente sigue respondiendo: solo que responde mal.

El asistente ignora sus instrucciones o responde algo que no viene al caso: Causa más probable: el contexto está truncado. La instrucción del sistema y las definiciones de herramientas superan la ventana cargada por Ollama, que corta una parte sin avisar. Compruebe la columna CONTEXT de ollama ps y repita el paso 1.
Se muestra JSON en lugar de la acción: El modelo formuló correctamente una llamada a una herramienta, pero la puerta de enlace la recibió como texto. Es señal de una dirección /v1 o de un proveedor declarado en modo compatible con OpenAI. Vuelve a la dirección nativa y a api: "ollama".
Describe lo que haría, sin hacer nada: El modelo no declara la capacidad tools, o es demasiado limitado para utilizarla en medio de una instrucción larga. Repite la prueba directa en Ollama descrita en el paso 4; si falla, cambia de modelo.
El modelo no aparece en openclaw models list: Tres posibilidades. El proveedor no está activado (falta la clave ficticia o la variable no se ha transmitido al servicio). Existe una entrada explícita models.providers.ollama que no incluye este modelo. O el modelo no declara la llamada a herramientas: según la documentación que conocemos, el descubrimiento automático solo conserva los que la declaran, un comportamiento que puede haber cambiado según las versiones.
El ajuste del contexto sigue sin tener efecto: La variable OLLAMA_CONTEXT_LENGTH se exportó en un terminal mientras Ollama se ejecuta como servicio o aplicación: el servidor nunca la vio. Declárala en el servicio o en los ajustes de la aplicación y luego reinicia Ollama.
Las respuestas tardan muchísimo o no llegan: O bien el modelo se desborda al procesador (columna PROCESSOR de ollama ps), o bien se descargó tras un periodo de inactividad y se vuelve a cargar con cada mensaje: de forma predeterminada, Ollama mantiene un modelo en memoria durante cinco minutos. La variable OLLAMA_KEEP_ALIVE prolonga este plazo.
Todo funciona en el terminal, nada desde la pasarela: La puerta de enlace se ejecuta en un contenedor y busca Ollama en su propio localhost. Consulta la sección sobre Docker.
«Model context window too small»: Esta no es silenciosa, pero desconcierta: las versiones de OpenClaw que conocemos rechazan un modelo cuya ventana anunciada es demasiado pequeña. Compruebe contextWindow en la declaración explícita y ajuste en consecuencia el contexto de Ollama.

Terminal — seguir los registros de ambos lados

# Passerelle OpenClaw
openclaw logs --follow

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

Un límite que conviene tener en cuenta una vez establecida la conexión: un modelo local correctamente conectado no se comportará necesariamente como un modelo grande en línea en tareas largas o ambiguas. Aquí no publicamos ninguna comparativa ni ninguna velocidad. Empieza por solicitudes sencillas y sin consecuencias, observa dónde falla el modelo y conserva un proveedor en línea como modelo de respaldo si el asistente te resulta útil en el día a día.

#Fuentes oficiales para tener a mano

Esta guía no se basa en ninguna prueba propia: no contiene duración, rendimiento ni puntuación. Los comandos y los nombres de los campos proceden de la documentación de los dos proyectos, que cambia de una versión a otra: opciones de ollama launch, comportamiento del descubrimiento automático y valores predeterminados. En caso de discrepancia entre esta página y la documentación, prevalece la documentación.

Ollama: integración con OpenClaw

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

OpenClaw: proveedor Ollama

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

Ollama: longitud del contexto

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

Ollama: preguntas frecuentes (variables del servidor)

https://docs.ollama.com/faq

OpenClaw: seguridad de la puerta de enlace

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

#Para ir más allá

La conexión se basa en tres conceptos tratados en detalle en otras partes del sitio: el servidor Ollama, la ventana de contexto y la llamada a herramientas.

Instalar Ollama: La instalación del servidor de modelos, sus ajustes básicos y lo que puede salir de la máquina. https://quelllm.fr/guide/installer-ollama
Comprender la ventana de contexto: Qué mide un token, por qué el contexto consume memoria y cómo dimensionarlo. https://quelllm.fr/guide/comprendre-fenetre-contexte
Llamada a herramientas con Ollama: El formato de las solicitudes de herramientas y cómo probarlas sin ningún agente. https://quelllm.fr/guide/appel-outil-ollama-tutoriel
Hermes Agent con Ollama: Otro agente autoalojado conectado a un modelo local, para comparar los enfoques. https://quelllm.fr/guide/hermes-agent-ollama-guide
Instalar OpenClaw con Docker: La instalación de la pasarela, su actualización y las reglas de exposición en un VPS. https://quelllm.fr/guide/installer-openclaw-docker

¿Esta guía te ha ayudado?

¿Un comentario, un error, una precisión? Avísanos, eso mejora la guía para todos.

Los kits de QuelLLMLa guía de referencia según el uso

Agentes Locales Copiloto Local IA local RAG Local IA en la empresa IA Sin Filtros Mac Imágenes IA

Todos los kits de por vida — 49 €