Uso de Ollama con Claude Code: Guía para configurar modelos locales

Claude Code es el agente oficial de programación en terminal de Anthropic y, por defecto, se comunica con la API en la nube de Anthropic. Ollama es un entorno local para ejecutar modelos que expone una API HTTP compatible con OpenAI. Ambos no hablan el mismo protocolo de forma nativa, por lo que vincularlos requiere una capa de proxy ligera que traduzca la API de mensajes de Anthropic a la API de chat de Ollama. Esta guía explica cómo funciona esto, qué modelos merece la pena ejecutar y dónde falla esta configuración.

Por qué Ollama y Claude Code no se conectan directamente

Claude Code envía solicitudes en el formato de la API de mensajes de Anthropic (/v1/messages), con campos específicos de Anthropic para el uso de herramientas, control de caché y indicaciones del sistema. Ollama expone /api/chat y un punto final compatible con OpenAI. /v1/chat/completions Ninguno de los dos habla el dialecto de Anthropic. Para conectarlos necesitas un proxy que:

• Acepte solicitudes en formato Anthropic en un punto final HTTPS.
• Las reescriba como completados de chat compatibles con OpenAI.
• Las redirija a Ollama y, posteriormente, traduzca las respuestas en streaming y las llamadas a herramientas de vuelta al flujo de eventos de Anthropic que Claude Code espera.

Dos proyectos gestionan esto de forma fiable a partir de 2026: claude-code-router (un router diseñado específicamente para Claude Code que soporta Ollama, OpenRouter y otros backends) y LiteLLM (un proxy de propósito general con un modo de anthropic paso directo). Cualquiera de los dos funciona; claude-code-router tiene menos componentes si Ollama es tu único backend.

Requisitos previos

• Ollama instalado y en ejecución. Consulta cómo instalar Ollama si aún no lo tienes.
• Claude Code instalado (npm install -g @anthropic-ai/claude-code).
• Al menos un modelo con capacidad de programación descargado localmente.
• Node.js 18+ para claude-code-router o Python 3.10+ para LiteLLM.

Verifica que Ollama sea accesible:

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

Elección de un modelo local

Claude Code depende fuertemente del uso de herramientas, ediciones estructuradas y razonamiento con contextos largos. Los modelos más pequeños orientados a conversación general manejan estas tareas deficientemente. Opta por modelos especializados en programación o modelos instruct grandes.

Modelo (etiqueta de Ollama)	Tamaños notables	VRAM aproximada (Q4)	Notas
qwen3-coder	30B (MoE A3B), 480B (MoE A35B)	~18 GB (30B); la variante de 480B está pensada para servidores	Línea de modelos para programación del equipo Qwen; destaca en el uso agéntico de herramientas.
deepseek-coder-v2	16B, 236B	~10 GB (16B lite)	Completados y refactorizaciones sólidos; la versión de 236B solo está disponible para servidores.
llama3.1	8B, 70B	~5 GB / ~40 GB	Modelo instruct general; el de 70B es un sustituto razonable de Claude si dispones de suficiente VRAM.
qwen2.5-coder	7B, 14B, 32B	~5 / ~9 / ~20 GB	Aún muy utilizado; anterior a qwen3-coder, pero muy estable.

El nivel de cuantización, la longitud del contexto y el tamaño de la caché KV afectan los requisitos de VRAM. Utilice la Calculadora de VRAM para dimensionar una configuración específica, y consulte mejores LLMs locales para Ollama para una comparación más amplia.

Descargue uno antes de configurar el proxy:

ollama pull qwen3-coder:30b
ollama pull deepseek-coder-v2:16b

Opción 1: claude-code-router

claude-code-router es la ruta más directa. Instálelo globalmente:

npm install -g @musistudio/claude-code-router

Cree ~/.claude-code-router/config.json:

{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen3-coder:30b", "deepseek-coder-v2:16b"]
    }
  ],
  "Router": {
    "default": "ollama,qwen3-coder:30b",
    "background": "ollama,deepseek-coder-v2:16b"
  }
}

Inicie Claude Code mediante el router:

ccr code

El router inicia un punto final local compatible con Anthropic, configura automáticamente las variables de entorno para Claude Code y enruta el tráfico hacia Ollama. Los nombres exactos de los campos de configuración han cambiado entre versiones menores; revise el README del proyecto si alguna clave es rechazada.

Opción 2: proxy LiteLLM

Si ya ejecuta LiteLLM para otros servicios, reutilícelo. Cree config.yaml:

model_list:
  - model_name: claude-sonnet-4
    litellm_params:
      model: ollama_chat/qwen3-coder:30b
      api_base: http://localhost:11434
  - model_name: claude-haiku-4
    litellm_params:
      model: ollama_chat/deepseek-coder-v2:16b
      api_base: http://localhost:11434

Ejecute lo siguiente:

litellm --config config.yaml --port 4000

Luego dirija Claude Code al proxy (consulte la siguiente sección). LiteLLM gestiona la traducción de Anthropic a Ollama en la ruta /anthropic .

Configuración de Claude Code para apuntar al proxy

Claude Code lee dos variables de entorno para redirigir su tráfico de API. Establézcalas en su shell antes de ejecutar claude.

macOS y Linux

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-anything"
claude

Agregue estas líneas a ~/.zshrc o ~/.bashrc para que persistan. El valor de la clave no se usa en el proxy local, pero Claude Code se niega a iniciarse si no se ha definido ninguna.

Windows (PowerShell)

$env:ANTHROPIC_BASE_URL="http://localhost:4000"
$env:ANTHROPIC_API_KEY="sk-anything"
claude

Para que persistan entre sesiones, use [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "http://localhost:4000", "User"). Si Claude Code está instalado mediante WSL, configure las variables dentro del shell de WSL en lugar de hacerlo en Windows; Ollama ejecutándose en Windows es accesible desde WSL en http://host.docker.internal:11434 o en la dirección IP del host de Windows.

Windows (nativo, sin WSL)

Claude Code tiene soporte oficial para macOS, Linux y WSL. El soporte nativo para Windows ha sido problemático históricamente; ejecute Claude Code bajo WSL2 a menos que haya verificado que la versión actual funciona correctamente en su sistema.

Configuración del contexto y los tiempos de espera

Claude Code asume un contexto de 200K tokens y un tiempo muy rápido hasta el primer token. Los modelos locales no cumplirán ninguno de estos requisitos. Dos parámetros clave requieren ajuste:

• Longitud del contexto en Ollama. Establézcala explícitamente por modelo mediante un Modelfile (PARÁMETRO num_ctx 32768) o mediante la variable de entorno OLLAMA_CONTEXT_LENGTH en el servidor Ollama. La longitud de contexto predeterminada es pequeña y truncará silenciosamente conversaciones largas.
• VRAM de la caché KV. Un contexto de 32K en un modelo de 30B consume varios GB únicamente para la caché KV. Verifique el uso total de memoria con ollama ps.

Para un desglose completo de los requisitos de memoria a distintos tamaños de contexto, consulte Requisitos de VRAM por modelo.

Limitaciones conocidas

• El uso de herramientas es frágil. Las herramientas de edición de archivos, bash y búsqueda de Claude Code dependen de una salida estricta en formato JSON para las llamadas a herramientas. Los modelos locales fallan con mayor frecuencia en este aspecto, generando llamadas mal formadas o «alucinando» contenidos de archivos. qwen3-coder y deepseek-coder-v2 son algunos de los más fiables, aunque ninguno iguala el rendimiento de Claude Sonnet.
• El almacenamiento en caché de indicaciones es un no-op. de Anthropic cache_control Los campos son ignorados por el proxy. Los indicadores del sistema largos se reenvían en cada turno.
• Velocidad. Incluso en una GPU de 24 GB, un modelo de 30B con contexto de 32K produce 15–40 tokens/seg. El bucle agente de Claude Code realiza muchas llamadas por tarea, por lo que el tiempo transcurrido puede ser 5–10× más lento que la API en la nube.
• Sub-agentes y MCP. Las características avanzadas de Claude Code (agentes de fondo, servidores MCP) generalmente siguen funcionando porque se enrutan a través del mismo proxy, pero cualquier característica que dependa del comportamiento específico del servidor Anthropic puede fallar silenciosamente.

Cuándo usar esta configuración frente a la API

Claude Code local tiene sentido cuando: el código no puede salir de tu red, estás en un presupuesto de API medido y realizas refactorizaciones en masa, o estás experimentando con auto-alojamiento. Tiene menos sentido para la codificación agente diaria donde el razonamiento de clase Sonnet es el punto.

Para decidir numéricamente, calcula los números en ambos lados. El Calculadora de costos de API estima el gasto mensual en Anthropic, y el Calculadora de punto de equilibrio entre auto-alojamiento e API compara eso contra la amortización de GPU. Para la mayoría de desarrolladores individuales la API gana; para equipos que usan mucho la API, una caja local compartida puede amortizarse en menos de un año. Si estás especificando esa caja, la mejores GPUs para LLMs locales guía cubre el nivel actual.

Alternativas a Ollama para este flujo de trabajo

Si el rendimiento de Ollama resulta limitante, otros entornos de ejecución con APIs compatibles con OpenAI funcionan de forma idéntica detrás del mismo proxy: LM StudiovLLM y el servidor de llama.cpp también son compatibles. Consulte la guía de LM Studio para una opción centrada en la interfaz gráfica de usuario, o la guía completa de Ollama para un análisis más profundo de Ollama en sí.

Preguntas Frecuentes

¿Puede Claude Code usar Ollama sin un proxy?

No. Claude Code se comunica mediante la API Messages de Anthropic y Ollama no implementa ese protocolo. Necesitas una capa de traducción, como claude-code-router o LiteLLM. Configurar ANTHROPIC_BASE_URL directamente como http://localhost:11434 fallará en la primera solicitud.

¿Qué modelo local se acerca más a Claude Sonnet para programación?

En los tamaños que la mayoría de las personas pueden ejecutar realmente, qwen3-coder (30B MoE) y deepseek-coder-v2 (16B lite) son las opciones actuales líderes. Ninguno iguala a Sonnet en tareas agénticas multiarchivo, pero ambos son utilizables para ediciones de un solo archivo, autocompletados y revisiones de código. Compara las puntuaciones de inteligencia en el Clasificación de modelos de lenguaje grande (LLM).

¿Funciona la caché de indicaciones con Ollama detrás de Claude Code?

No. La caché de indicaciones de Anthropic es una función del lado del servidor de su API. Los proxies eliminan o ignoran los campos cache_control por lo que cada solicitud vuelve a procesar íntegramente la indicación del sistema y el historial de conversación. Esta es una de las razones por las que las configuraciones locales parecen más lentas por turno que la API en la nube, incluso con un rendimiento similar en tokens brutos por segundo.

¿Cuánta VRAM necesito para una experiencia aceptable?

Una sola GPU de 24 GB (clase RTX 3090/4090/5090) ejecuta un modelo codificador de 30B en cuantización Q4 con aproximadamente 32K de contexto. Para modelos de clase 70B o contextos más largos, planifica al menos 48 GB (RTX 6000 Ada, dos RTX 3090) o más. Usa el Calculadora de VRAM para obtener cifras exactas por modelo y cuantización.

¿Puedo mezclar modelos locales y en la nube en la misma sesión de Claude Code?

Sí, mediante un router. claude-code-router te permite asignar distintos modelos a distintos roles; por ejemplo, Sonnet en la nube para el agente principal y un modelo local para tareas secundarias o autocompletados. Esto puede reducir sustancialmente los costos de la API manteniendo una alta calidad en la ruta crítica.

¿Existe una forma oficial respaldada por Anthropic para ejecutar Claude Code localmente?

No. Anthropic distribuye Claude Code como cliente de su API y no publica los pesos de Claude. Todas las configuraciones locales son proxies comunitarios que apuntan a modelos de terceros. Si Anthropic modifica la API Messages, los proxies podrían requerir actualizaciones antes de que Claude Code vuelva a funcionar correctamente con ellos.