OpenClaw con Ollama: modelos locales sin coste de API

Ollama expone por defecto dos APIs en el puerto 11434: su propia API nativa (/api/generate, /api/chat) y una capa de compatibilidad con OpenAI (/v1/chat/completions, /v1/models). OpenClaw usa esta segunda capa, que convierte cualquier modelo de Ollama en un "proveedor OpenAI-compatible".

Este diseño tiene una ventaja importante: no necesitas ninguna clave de API real. Ollama no autentica las peticiones locales, así que puedes poner cualquier cadena como api_key en la configuración de OpenClaw. El tráfico nunca sale de tu máquina.

1. Instalar y arrancar Ollama

Si aún no tienes Ollama, la guía de Ollama cubre la instalación completa en Linux, macOS y Windows. En resumen:

# Linux / macOS
curl -fsSL https://ollama.com/install.sh | sh

# Arrancar el servidor (queda en segundo plano)
ollama serve

# Descargar un modelo compatible
ollama pull llama3.1:8b
ollama pull qwen2.5:14b
ollama pull mistral:7b

# Verificar que el endpoint está accesible
curl http://localhost:11434/api/tags

2. Verificar el endpoint compatible con OpenAI

Ollama expone la API compatible con OpenAI en /v1. Verifica que funciona antes de configurar OpenClaw:

# Listar modelos disponibles (formato OpenAI)
curl http://localhost:11434/v1/models

# Enviar una petición de prueba
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [{"role": "user", "content": "Hola, responde en una frase."}]
  }'

Si recibes una respuesta JSON con el campo choices, el endpoint funciona correctamente y OpenClaw podrá conectarse.

Método A: edición directa de openclaw.json

El archivo de configuración principal de OpenClaw está en ~/.openclaw/openclaw.json. Para añadir Ollama como proveedor, edita la sección providers:

{
  "gateway": {
    "port": 18789
  },
  "providers": {
    "ollama-local": {
      "type": "openai-compatible",
      "baseUrl": "http://127.0.0.1:11434/v1",
      "apiKey": "ollama-local",
      "models": ["llama3.1:8b", "qwen2.5:14b", "mistral:7b"]
    }
  },
  "agents": {
    "defaults": {
      "provider": "ollama-local",
      "model": "qwen2.5:14b"
    }
  }
}

Método B: CLI de OpenClaw

# Añadir Ollama como proveedor vía CLI
openclaw config set providers.ollama-local.type openai-compatible
openclaw config set providers.ollama-local.baseUrl http://127.0.0.1:11434/v1
openclaw config set providers.ollama-local.apiKey ollama-local

# Establecer Ollama como proveedor por defecto
openclaw config set agents.defaults.provider ollama-local
openclaw config set agents.defaults.model qwen2.5:14b

# Verificar la configuración
openclaw config show

# Probar la conexión
openclaw test-provider ollama-local

Verificar la integración

# Arrancar el gateway con el nuevo proveedor
openclaw start

# En otra terminal, enviar un mensaje de prueba vía CLI
openclaw chat "Hola, ¿qué modelo eres?"

# El gateway debería responder indicando que usa el modelo de Ollama configurado

Latencia: el principal inconveniente

Con una GPU dedicada moderna (RTX 3080 o superior), los modelos de 7-14B generan texto a 40-80 tokens por segundo, lo que se traduce en respuestas perceptibles en 1-3 segundos para mensajes cortos. En CPU sin GPU dedicada, la velocidad cae a 3-10 tokens por segundo, resultando en tiempos de respuesta de 10-30 segundos para respuestas medianas. Para uso como agente de mensajería, esto puede ser aceptable; para conversaciones rápidas, es un handicap notable.

Otras limitaciones frente a Claude

• Ventana de contexto: la mayoría de modelos de Ollama tienen contextos de 8K-128K tokens. Claude Sonnet 4.6 y Opus 4.7 soportan hasta 1M tokens; Haiku 4.5 soporta 200K. Para conversaciones largas o documentos grandes, esto es una limitación real.
• Calidad del function calling: los modelos locales tienen mayor tasa de error en function calling complejo (múltiples herramientas encadenadas, parámetros anidados). OpenClaw implementa reintentos automáticos, pero la fiabilidad es menor.
• Razonamiento complejo: los modelos de 7-14B tienen capacidades de razonamiento significativamente inferiores a Claude Opus o GPT-5 para tareas que requieren múltiples pasos de lógica, código complejo o análisis profundo.
• Soporte de idiomas: el español tiene cobertura más irregular que el inglés en modelos como Llama. Qwen 2.5 es la mejor opción si necesitas soporte nativo de español.

Escenario: ambos en el host (configuración más simple)

# Ollama en el host, OpenClaw en el host
# Configuración estándar — funciona sin cambios
baseUrl: "http://127.0.0.1:11434/v1"

Escenario: OpenClaw en Docker, Ollama en el host

# Docker Desktop (macOS o Windows)
baseUrl: "http://host.docker.internal:11434/v1"

# Linux con --network=host
# El contenedor usa la red del host directamente
docker run --network=host openclaw/openclaw
# Y entonces puedes usar:
baseUrl: "http://127.0.0.1:11434/v1"

Escenario: ambos en Docker con Compose

version: "3.9"
services:
  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "18789:18789"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434/v1
    depends_on:
      - ollama

volumes:
  ollama_data:

En el escenario de Docker Compose, los contenedores se comunican por nombre de servicio. El baseUrl en la configuración de OpenClaw debe ser http://ollama:11434/v1 (usando el nombre del servicio ollama, no 127.0.0.1).

{
  "gateway": {
    "port": 18789,
    "host": "127.0.0.1"
  },

  "providers": {
    "ollama-local": {
      "type": "openai-compatible",
      "baseUrl": "http://127.0.0.1:11434/v1",
      "apiKey": "ollama-local",
      "models": [
        "qwen2.5:14b",
        "llama3.1:8b",
        "mistral:7b",
        "llama3.2:3b"
      ],
      "defaultModel": "qwen2.5:14b",
      "timeout": 120000
    },
    "anthropic-fallback": {
      "type": "anthropic",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "defaultModel": "claude-haiku-4-5"
    }
  },

  "agents": {
    "defaults": {
      "provider": "ollama-local",
      "model": "qwen2.5:14b",
      "workspace": "~/.openclaw/workspace",
      "systemPrompt": "Eres un asistente personal. Responde siempre en español.",
      "maxTokens": 4096,
      "temperature": 0.7
    }
  },

  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}"
    },
    "whatsapp": {
      "enabled": false
    }
  }
}

Las variables de entorno (${ANTHROPIC_API_KEY}, ${TELEGRAM_BOT_TOKEN}) se leen del entorno del proceso o de un archivo .env en el directorio de trabajo. Nunca pongas claves directamente en el JSON si el archivo va a estar en un repositorio de control de versiones.

Arrancar y verificar

# Arrancar con la configuración completa
openclaw start

# Verificar que el proveedor Ollama está activo
openclaw status

# Enviar un mensaje de prueba
openclaw chat "¿Qué modelo estás usando ahora mismo?"

# Ver los logs del gateway en tiempo real
openclaw logs --follow