Conecta Claude Code a un modelo local con Ollama: subagentes y búsqueda web sin enviar tu código a la nube
Al terminar este artículo, Claude Code estará funcionando contra un modelo servido por Ollama en tu propia máquina, y sabrás con exactitud qué partes de una sesión salen del edificio. El punto de entrada más barato: un portátil de 16 GB y un modelo de 9B. El cómodo para programar de verdad: 24 GB y un modelo de 26B.
La fuente es el artículo de Ollama Subagents and web search in Claude Code (16 de febrero de 2026) y la documentación de integración de Claude Code. El artículo de Ollama usa modelos alojados en su nube; aquí todo es local, y probamos la configuración en nuestra estación de trabajo el 09-09-2026.
Qué necesitas
- Ollama instalado (
ollama --version). Nosotros usamos la 0.30.10; el endpoint compatible con Anthropic respondió enlocalhost:11434/v1/messages. - Claude Code instalado:
curl -fsSL https://claude.ai/install.sh | bash(macOS/Linux) oirm https://claude.ai/install.ps1 | iex(Windows). Nosotros ejecutamos la 2.1.266. - Un modelo con la capacidad
toolsque quepa en tu memoria (tabla en el paso 2). - Para la ruta local no hace falta cuenta de Anthropic. Ni tarjeta ni clave.
Paso 1: define tres variables de entorno
Salen tal cual de la documentación de integración:
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434
claude --model gemma4:26bEl atajo ollama launch claude --model gemma4:26b escribe la misma configuración por ti; ollama launch claude --restore la deshace. Preferimos las variables porque viven en una sola terminal y no tocan tu inicio de sesión habitual de Claude Code.
Comportamiento esperado: Claude Code arranca y la primera petición aparece en ollama ps. Dos avisos son normales. Claude Code dice que el modelo no está en su catálogo y asume una ventana de 200k tokens; fija CLAUDE_CODE_MAX_CONTEXT_TOKENS al contexto que de verdad le hayas dado a Ollama. Y avisa de que los conectores de claude.ai quedan desactivados mientras ANTHROPIC_API_KEY esté definida, que es justo lo que quieres aquí.
Paso 2: elige un modelo que quepa y dale contexto suficiente
La documentación recomienda 64k tokens de contexto para bases de código grandes. El contexto cuesta memoria: en nuestra máquina, qwen3.6:35b ocupó 23 GB con 32k de contexto y 29 GB con sus 262k completos. Fija la ventana de forma explícita en lugar de heredar un valor por defecto:
export OLLAMA_CONTEXT_LENGTH=65536 # o 32768 en una máquina justa
ollama ps # la columna CONTEXT lo confirmaLos tamaños de descarga vienen de las páginas de la biblioteca de Ollama de qwen3.5, gemma4 y qwen3-coder. La memoria residente es la que vimos en ollama ps con 32k de contexto.
| Máquina | Modelo | Descarga | Residente con 32k | Veredicto |
|---|---|---|---|---|
| 16 GB | qwen3.5:9b | 6,6 GB | no medido aquí | Cabe con sitio para el editor |
| 16 GB | gemma4:12b | 7,6 GB | no medido aquí | Cabe; mantén el contexto en 32k |
| 16 GB | qwen2.5-coder:7b | 4,7 GB | 6,6 GB | Cabe, pero mira la prueba de abajo |
| 24 GB | gemma4:26b | 19 GB | 17 GB | Cabe con 32k; deja unos 6 GB |
| 24 GB | qwen3.5:27b | 17 GB | no medido aquí | Cabe con 32k, justo con 64k |
| 24 GB | qwen3-coder:30b | 19 GB | no medido aquí | Cabe solo con 32k |
| 32 GB o más | qwen3.6:35b | 23 GB | 23 GB | Cómodo con 32k |
Paso 3: repite la misma prueba que hicimos nosotros
El modo no interactivo hace la prueba repetible. Desde una carpeta vacía:
env ANTHROPIC_BASE_URL=http://localhost:11434 ANTHROPIC_AUTH_TOKEN=ollama ANTHROPIC_API_KEY= \
claude -p --model gemma4:26b "Responde exactamente con estas tres palabras: modelo local listo"Nuestros resultados en la estación NVIDIA GB10 (128 GB de memoria unificada), 09-09-2026, con el tiempo de reloj incluyendo la carga del modelo:
| Modelo | Salida | Tiempo total | Velocidad de generación (/api/generate) |
|---|---|---|---|
qwen2.5-coder:7b | {"name": "local-model-ready", "arguments": {}} | 28 s | 34,1 tokens/s |
gemma4:26b | local model ready | 1 min 32 s | 51,2 tokens/s |
qwen3.6:35b | local model ready | 1 min 45 s | 51,4 tokens/s |
El modelo de 7B para código es rápido, pero respondió al prompt de sistema de Claude Code, cargado de herramientas, con una llamada a herramienta mal formada en lugar de texto. Esa es la foto honesta del nivel de 16 GB: el chat y las ediciones de un solo archivo funcionan; las sesiones agénticas se confunden. Los modelos de 26B y 35B se comportaron. Los tiempos largos son casi por completo la primera carga desde disco (116 s para gemma4:26b); la segunda ejecución tarda segundos.
Paso 4: usa subagentes sabiendo lo que cuestan
Los subagentes dan a las tareas secundarias su propio contexto para que la sesión principal se mantenga limpia. El artículo de Ollama dice que modelos como minimax-m2.5, glm-5 y kimi-k2.5 los lanzan por su cuenta; con un modelo local, pídelo de forma explícita: “Usa subagentes para revisar los tests y la documentación en paralelo mientras refactorizas el parser.”
Cada subagente es otra petición al mismo servidor de Ollama. En una sola GPU comparten los mismos tokens por segundo, así que tres subagentes en paralelo sobre un modelo de 26B se sienten como una sesión a un tercio de velocidad. En hardware local, úsalos para aislar tareas, no para ganar velocidad.
Qué corre en local y qué no
Aquí conviene ser preciso.
| Componente | Dónde corre | Notas |
|---|---|---|
| Tu código, prompts, ediciones, llamadas a herramientas | Tu máquina | Solo se envían a localhost:11434 |
| El modelo | Tu máquina | Ollama, en GPU o CPU |
| Subagentes | Tu máquina | Peticiones adicionales al mismo Ollama |
| Búsqueda y lectura web | Servicio alojado de Ollama | POST https://ollama.com/api/web_search; requiere cuenta gratuita, ollama signin (documentación) |
| Actualizaciones del binario de Claude Code | Servidores de Anthropic | Como en cualquier instalación |
La búsqueda web es la única función que sale del edificio. El artículo de Ollama la describe como integrada en la capa de compatibilidad con Anthropic: cuando el modelo quiere información actual, Ollama ejecuta la búsqueda y devuelve los resultados al contexto local. Solo viaja la consulta, no tu repositorio. Si tu política es estrictamente local, no inicies sesión y el modelo sencillamente no tendrá herramienta de búsqueda; o aloja tú un buscador como SearXNG y exponlo con un servidor MCP, que es lo que hacemos nosotros.
Dónde encaja y los límites frente a los modelos alojados
Claude Code en local es la opción correcta para código que no puedes enviar a ningún sitio, para trabajar sin conexión y para el 80 por ciento repetitivo: tests, docstrings, refactorizaciones pequeñas, explicar un archivo desconocido. Reserva un modelo alojado con límite de gasto para el 20 por ciento difícil.
Límites, con honestidad. Un modelo local de 26B no iguala a uno de primera línea en cambios de arquitectura sobre muchos archivos ni en ejecuciones largas de agente; espera más turnos y más supervisión. Generar a 51 tokens por segundo con un modelo de 26B es más lento que los modelos alojados, y una máquina de 24 GB ejecuta un solo modelo de ese tamaño a la vez. La visión y el razonamiento funcionan solo si el modelo los soporta (ollama show lista las capacidades). Y Claude Code asume una ventana de 200k para modelos desconocidos, así que dile la verdad con CLAUDE_CODE_MAX_CONTEXT_TOKENS.
Siguientes pasos
- Elige la máquina para el nivel que necesitas: Mejores dispositivos para IA local en 2026.
- Compara las familias de modelos antes de descargar 20 GB: Mejores modelos LLM locales, comparativa del segundo trimestre de 2026.
- Calcula cuándo la máquina gana a la suscripción: Nube o local: punto de equilibrio.
Trabaja con nosotros
Usamos Claude Code contra modelos locales a diario y mantenemos una clave alojada solo para los casos difíciles. Si quieres ese reparto diseñado para tu equipo, con los modelos dimensionados a los portátiles que ya tenéis, escríbenos o mira cómo trabajamos en consultoría.