Ollama

Ollama es un entorno de ejecucion local de LLM que facilita ejecutar modelos de codigo abierto en tu maquina. OpenClaw se integra con la API nativa de Ollama (/api/chat), soporta streaming y llamadas a herramientas, y puede descubrir automaticamente los modelos locales de Ollama cuando activas OLLAMA_API_KEY (o un perfil de autenticacion) y no defines una entrada explicita models.providers.ollama.

Advertencia: Usuarios de Ollama remoto: No uses la URL compatible con OpenAI /v1 (http://host:11434/v1) con OpenClaw. Esto rompe las llamadas a herramientas y los modelos pueden generar JSON de herramientas como texto plano. Usa la URL de la API nativa de Ollama: baseUrl: "http://host:11434" (sin /v1).

Inicio rapido

Asistente de configuracion (recomendado)

La forma mas rapida de configurar Ollama es a traves del asistente de configuracion:

openclaw onboard

Selecciona Ollama de la lista de proveedores. El asistente:

  1. Te pedira la URL base de Ollama donde se puede acceder a tu instancia (por defecto http://127.0.0.1:11434).
  2. Te permitira elegir Cloud + Local (modelos en la nube y locales) o Local (solo modelos locales).
  3. Abrira un flujo de inicio de sesion en el navegador si eliges Cloud + Local y no has iniciado sesion en ollama.com.
  4. Descubrira los modelos disponibles y sugerira valores predeterminados.
  5. Descargara automaticamente el modelo seleccionado si no esta disponible localmente.

El modo no interactivo tambien esta soportado:

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk

Opcionalmente puedes especificar una URL base o modelo personalizado:

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

Configuracion manual

  1. Instala Ollama: https://ollama.com/download

  2. Descarga un modelo local si quieres inferencia local:

ollama pull glm-4.7-flash
# o
ollama pull gpt-oss:20b
# o
ollama pull llama3.3
  1. Si tambien quieres modelos en la nube, inicia sesion:
ollama signin
  1. Ejecuta la configuracion y elige Ollama:
openclaw onboard
  • Local: solo modelos locales
  • Cloud + Local: modelos locales mas modelos en la nube
  • Los modelos en la nube como kimi-k2.5:cloud, minimax-m2.5:cloud y glm-5:cloud no requieren un ollama pull local

OpenClaw actualmente sugiere:

  • predeterminado local: glm-4.7-flash
  • predeterminados en la nube: kimi-k2.5:cloud, minimax-m2.5:cloud, glm-5:cloud
  1. Si prefieres la configuracion manual, habilita Ollama para OpenClaw directamente (cualquier valor sirve; Ollama no requiere una clave real):
# Establecer variable de entorno
export OLLAMA_API_KEY="ollama-local"

# O configurar en tu archivo de configuracion
openclaw config set models.providers.ollama.apiKey "ollama-local"
  1. Inspecciona o cambia de modelo:
openclaw models list
openclaw models set ollama/glm-4.7-flash
  1. O establece el modelo predeterminado en la configuracion:
{
  agents: {
    defaults: {
      model: { primary: "ollama/glm-4.7-flash" },
    },
  },
}

Descubrimiento de modelos (proveedor implicito)

Cuando estableces OLLAMA_API_KEY (o un perfil de autenticacion) y no defines models.providers.ollama, OpenClaw descubre los modelos de la instancia local de Ollama en http://127.0.0.1:11434:

  • Consulta /api/tags
  • Usa consultas /api/show con el mejor esfuerzo para leer contextWindow cuando esta disponible
  • Marca reasoning con una heuristica del nombre del modelo (r1, reasoning, think)
  • Establece maxTokens al limite maximo predeterminado de tokens de Ollama usado por OpenClaw
  • Establece todos los costos en 0

Esto evita entradas manuales de modelos mientras mantiene el catalogo alineado con la instancia local de Ollama.

Para ver que modelos estan disponibles:

ollama list
openclaw models list

Para agregar un nuevo modelo, simplemente descargalo con Ollama:

ollama pull mistral

El nuevo modelo se descubrira automaticamente y estara disponible para usar.

Si estableces models.providers.ollama explicitamente, el descubrimiento automatico se omite y debes definir los modelos manualmente (ver mas abajo).

Configuracion

Configuracion basica (descubrimiento implicito)

La forma mas sencilla de habilitar Ollama es mediante una variable de entorno:

export OLLAMA_API_KEY="ollama-local"

Configuracion explicita (modelos manuales)

Usa la configuracion explicita cuando:

  • Ollama se ejecuta en otro host/puerto.
  • Quieres forzar ventanas de contexto o listas de modelos especificas.
  • Quieres definiciones de modelos completamente manuales.
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host: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: 8192,
            maxTokens: 8192 * 10
          }
        ]
      }
    }
  }
}

Si OLLAMA_API_KEY esta establecida, puedes omitir apiKey en la entrada del proveedor y OpenClaw la completara para las verificaciones de disponibilidad.

URL base personalizada (configuracion explicita)

Si Ollama se ejecuta en un host o puerto diferente (la configuracion explicita desactiva el descubrimiento automatico, asi que define los modelos manualmente):

{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434", // Sin /v1 - usa la URL de la API nativa de Ollama
        api: "ollama", // Establece explicitamente para garantizar el comportamiento nativo de llamadas a herramientas
      },
    },
  },
}

Advertencia: No agregues /v1 a la URL. La ruta /v1 usa el modo compatible con OpenAI, donde las llamadas a herramientas no son confiables. Usa la URL base de Ollama sin sufijo de ruta.

Seleccion de modelo

Una vez configurado, todos tus modelos de Ollama estan disponibles:

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}

Modelos en la nube

Los modelos en la nube te permiten ejecutar modelos alojados en la nube (por ejemplo kimi-k2.5:cloud, minimax-m2.5:cloud, glm-5:cloud) junto con tus modelos locales.

Para usar modelos en la nube, selecciona el modo Cloud + Local durante la configuracion. El asistente verifica si has iniciado sesion y abre un flujo de inicio de sesion en el navegador cuando es necesario. Si la autenticacion no puede verificarse, el asistente recurre a los modelos locales predeterminados.

Tambien puedes iniciar sesion directamente en ollama.com/signin.

Avanzado

Modelos de razonamiento

OpenClaw trata los modelos con nombres como deepseek-r1, reasoning o think como capaces de razonamiento por defecto:

ollama pull deepseek-r1:32b

Costos de modelos

Ollama es gratuito y se ejecuta localmente, por lo que todos los costos de modelos estan establecidos en $0.

Configuracion de streaming

La integracion de Ollama en OpenClaw usa la API nativa de Ollama (/api/chat) por defecto, que soporta completamente streaming y llamadas a herramientas simultaneamente. No se necesita configuracion especial.

Modo heredado compatible con OpenAI

Advertencia: Las llamadas a herramientas no son confiables en el modo compatible con OpenAI. Usa este modo solo si necesitas el formato OpenAI para un proxy y no dependes del comportamiento nativo de llamadas a herramientas.

Si necesitas usar el endpoint compatible con OpenAI (por ejemplo, detras de un proxy que solo soporta el formato OpenAI), establece api: "openai-completions" explicitamente:

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

Este modo puede no soportar streaming y llamadas a herramientas simultaneamente. Puede que necesites desactivar el streaming con params: { streaming: false } en la configuracion del modelo.

Cuando se usa api: "openai-completions" con Ollama, OpenClaw inyecta options.num_ctx por defecto para que Ollama no recurra silenciosamente a una ventana de contexto de 4096. Si tu proxy/upstream rechaza campos options desconocidos, desactiva este comportamiento:

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

Ventanas de contexto

Para modelos descubiertos automaticamente, OpenClaw usa la ventana de contexto reportada por Ollama cuando esta disponible; de lo contrario, recurre a la ventana de contexto predeterminada de Ollama usada por OpenClaw. Puedes anular contextWindow y maxTokens en la configuracion explicita del proveedor.

Solucion de problemas

Ollama no detectado

Asegurate de que Ollama este ejecutandose, que hayas establecido OLLAMA_API_KEY (o un perfil de autenticacion) y que no hayas definido una entrada explicita models.providers.ollama:

ollama serve

Y que la API sea accesible:

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

No hay modelos disponibles

Si tu modelo no aparece en la lista, puedes:

  • Descargar el modelo localmente, o
  • Definir el modelo explicitamente en models.providers.ollama.

Para agregar modelos:

ollama list  # Ver que esta instalado
ollama pull glm-4.7-flash
ollama pull gpt-oss:20b
ollama pull llama3.3     # U otro modelo

Conexion rechazada

Verifica que Ollama este ejecutandose en el puerto correcto:

# Verificar si Ollama esta ejecutandose
ps aux | grep ollama

# O reiniciar Ollama
ollama serve

Ver tambien

arrow_back
Anterior
Nvidia
Siguiente
Openai
arrow_forward