# Ollama en Windows: instala, descarga un modelo y úsalo con un agente de programación

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/ollama-modelos-locales-agente-programacion/

## ¿Qué vas a aprender?

- Qué es **Ollama** y para qué sirve tener modelos de IA en tu propio equipo.
- Instalar Ollama en Windows y comprobar que funciona.
- Descargar un modelo, probarlo en la terminal y gestionar los modelos descargados.
- Preparar el contexto que necesitan los agentes de programación.
- Conectar un agente (**OpenCode** o **Claude Code**) a tu modelo local.

## Requisitos previos

- **Windows 10 22H2** o posterior (Home o Pro); no hacen falta permisos de administrador. También macOS 14 o posterior y Linux.
- Una tarjeta gráfica ayuda mucho: **NVIDIA** con controlador 551.61 o posterior, o **AMD** compatible. Sin ella funciona con el procesador, más despacio.
- Espacio en disco: unos 4 GB para Ollama y, además, lo que ocupe cada modelo (de unos pocos GB a cientos).
- Para el último paso, un agente instalado: OpenCode o Claude Code (ver la guía de configuración básica de un agente de IA).

## Paso a paso

### Instalar Ollama

```powershell
# Opción 1: instalador para Windows (OllamaSetup.exe, en https://ollama.com/download)
# Opción 2: desde PowerShell
irm https://ollama.com/install.ps1 | iex

# Comprueba la versión y que el servicio responde
ollama -v
curl.exe http://localhost:11434
```

```bash
# Linux (y macOS)
curl -fsSL https://ollama.com/install.sh | sh
ollama -v
```

### Descargar y gestionar modelos

```powershell
# Descarga un modelo y chatea con él en la terminal (sal con /bye)
ollama pull qwen3.5
ollama run qwen3.5

# Gestiona los modelos
ollama ls                 # los modelos descargados
ollama ps                 # los que están cargados ahora (y si usan GPU o CPU)
ollama stop qwen3.5       # descarga el modelo de la memoria
ollama rm qwen3.5         # borra el modelo del disco
```

| Modelo | Etiqueta | Descarga aproximada |
|---|---|---|
| Qwen3.5 | qwen3.5 (9b) | 7 GB |
| Qwen2.5-Coder | qwen2.5-coder:7b / :14b / :32b | 4,7 / 9 / 20 GB |
| Devstral | devstral (24b) | 14 GB |
| gpt-oss | gpt-oss:20b | 14 GB |
| Qwen3-Coder | qwen3-coder (30b) | 19 GB |

### API local

```powershell
# API nativa de Ollama (adaptación a PowerShell del ejemplo con curl de la documentación)
Invoke-RestMethod -Uri http://localhost:11434/api/generate -Method Post -ContentType 'application/json' `
  -Body '{"model":"qwen3.5","prompt":"Escribe una función en Python que sume dos números","stream":false}'

# API compatible con OpenAI, para herramientas que ya la usan:
#   http://localhost:11434/v1/   (piden una clave, pero Ollama la ignora)
```

### Contexto para agentes (OLLAMA_CONTEXT_LENGTH)

1. Cierra Ollama desde el icono de la barra de tareas.
2. Busca «variables de entorno» en Configuración y abre «Editar las variables de entorno de tu cuenta».
3. Crea la variable OLLAMA_CONTEXT_LENGTH con el valor 64000.
4. Pulsa Aceptar y vuelve a abrir Ollama desde el menú Inicio.

### Conectar un agente

```powershell
# Abre un agente ya conectado a Ollama (si no indicas modelo, te deja elegir)
ollama launch opencode --model qwen3.5
ollama launch claude --model qwen3.5

# Solo configurar OpenCode para usar Ollama, sin abrirlo
ollama launch opencode --config
```

```powershell
# Claude Code contra Ollama, a mano (solo para esta ventana de PowerShell)
$env:ANTHROPIC_AUTH_TOKEN = "ollama"
$env:ANTHROPIC_API_KEY = ""
$env:ANTHROPIC_BASE_URL = "http://localhost:11434"
claude --model qwen3.5
# Dentro de Claude Code, /status muestra a qué se está conectando
```

## Errores habituales

- **curl.exe http://localhost:11434 no responde**: Ollama no está en marcha. Ábrelo desde el menú Inicio (debe aparecer su icono en la barra de tareas) y vuelve a probar. Revisa los registros en `%LOCALAPPDATA%\Ollama` (`server.log` y `app.log`).
- **El modelo va muy lento**: Mira `ollama ps`: si la columna PROCESSOR indica CPU o un reparto entre CPU y GPU, el modelo no cabe en la memoria de tu tarjeta gráfica. Usa un modelo más pequeño o reduce el contexto. Comprueba también que el controlador de NVIDIA es el 551.61 o posterior.
- **El agente no usa bien las herramientas o «olvida» lo anterior**: El contexto es demasiado pequeño. Sube `OLLAMA_CONTEXT_LENGTH` a 64000 o más (paso 5) y reinicia Ollama. También ayuda usar un modelo pensado para programar.
- **He cambiado una variable de entorno y no hace nada**: Ollama lee las variables al arrancar. Ciérralo desde el icono de la barra de tareas (no basta con cerrar la ventana) y vuelve a abrirlo desde el menú Inicio.
- **Me quedo sin espacio en disco**: Revisa lo descargado con `ollama ls` y borra lo que no uses con `ollama rm`. Los modelos se guardan en `C:\Users\<usuario>\.ollama\models`; para guardarlos en otro disco, define `OLLAMA_MODELS` como en el paso 5.
- **No descarga modelos detrás del proxy de la empresa**: Define la variable `HTTPS_PROXY` con la dirección del proxy (no uses `HTTP_PROXY`) y reinicia Ollama.

## Siguientes pasos

- Configurar el agente, su contexto y sus permisos (ver la guía de configuración básica para programar con un agente de IA).
- Comparar varios modelos de la biblioteca con una misma tarea de tu proyecto antes de elegir uno.
- Integrar la API local en tus aplicaciones con la compatibilidad con OpenAI (`http://localhost:11434/v1/`).
- Combinar modelos locales para tareas con datos sensibles y modelos en la nube para las más complejas.
