Usar un modelo local en Claude Code con Ollama y volver a la nube

Claude Code puede usar un modelo local mediante la API compatible con Anthropic de Ollama, pero recibir una respuesta de chat no demuestra que el modelo esté preparado para actuar como agente de programación. Antes de confiarle trabajo real, comprueba tres condiciones: soporte de llamadas a herramientas, capacidad del equipo para mantener al menos 64k de contexto y una tarea lo bastante acotada como para validarla con comandos y un diff.

Esta guía mantiene el cambio reversible. Conectarás Claude Code a qwen3.5 por la ruta oficial de Ollama, ejecutarás una prueba de aceptación sobre un solo archivo, comprobarás si la inferencia ocurre realmente en local, revisarás los límites de la API y de los datos, y eliminarás la configuración local antes de volver a un endpoint en la nube. Los comandos usan Bash en macOS, Linux o WSL. Son pasos para que los ejecutes tú, no resultados que este artículo afirme haber obtenido en tu equipo.

Decide primero: local, nube o un flujo híbrido

Los modelos locales funcionan mejor cuando la tarea tiene límites claros y el resultado puede verificarse de forma mecánica. Un repositorio grande, una migración entre servicios o una depuración compleja suelen aprovechar mejor un modelo en la nube que un modelo local pequeño con una descarga importante hacia CPU.

Tipo de trabajo	Punto de partida recomendado	Motivo
Arreglo de un archivo, una prueba nueva o explicación de una función concreta	Probar local primero	El contexto está acotado y el resultado se valida con un comando y un diff
Módulo pequeño o mediano con dependencias claras	Local o híbrido	Supera primero la prueba mínima y amplía el alcance poco a poco
Monorepo grande, refactorización entre servicios o investigación compleja	Nube primero	Requiere más contexto efectivo y planificación de herramientas más fiable
El modelo no sostiene 64k sin una descarga considerable a CPU	Nube primero	La latencia y los bloqueos eliminan buena parte de la ventaja local
El flujo depende de prompt caching, Batches API, bloques PDF o conteo exacto de tokens	Nube primero	Ollama implementa actualmente solo una parte de Anthropic Messages API
El código no puede enviarse a un modelo remoto	Local, desactivando funciones cloud	Aun así hay que auditar web tools, servidores MCP y comandos de shell

Una política híbrida útil es mantener en local los cambios pequeños y repetibles, y pasar de forma explícita a la nube para razonamiento sobre todo el repositorio, funciones de API no compatibles o fallos locales reiterados. Así conservas una sola interfaz de Claude Code sin fingir que ambos backends se comportan igual.

Paso 1: elige un modelo con herramientas y asigna 64k de contexto

Claude Code necesita algo más que generación de texto. El modelo debe producir llamadas a herramientas de forma estable para que el cliente lea archivos, aplique cambios y ejecute comandos. La página de Qwen3.5 en Ollama anuncia soporte de tools e incluye el comando de lanzamiento para Claude Code. También puedes inspeccionar el modelo exacto que has descargado con la API de detalles de Ollama.

Descarga el modelo y revisa capabilities:

ollama pull qwen3.5

curl http://localhost:11434/api/show \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5"}'

Antes de seguir, confirma que capabilities contiene tools. Si no aparece, una conversación normal no sustituye a la validación del agente. Elige en la biblioteca actual de Ollama un modelo marcado expresamente para herramientas, descárgalo y repite la comprobación.

El contexto es el segundo filtro. La documentación de longitud de contexto de Ollama indica que web search, agentes y herramientas de programación deberían usar al menos 64.000 tokens, y que ampliar el contexto aumenta el consumo de memoria. En la aplicación de Ollama, configura el control de context length en 64000 o más. Si arrancas el servicio desde una shell, detén antes la instancia existente y ejecuta esto en un terminal dedicado:

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

Mantén ese terminal abierto. Espera a que el servidor arranque y continúa en un segundo terminal. Si el puerto ya está ocupado, ya existe una instancia de Ollama; cambia su configuración de contexto en lugar de iniciar otra.

Paso 2: inicia Claude Code con la integración oficial de Ollama

La ruta oficial más corta es:

ollama launch claude --model qwen3.5

Es la forma más sencilla de establecer la integración. Cuando Claude Code se abra, ejecuta /status y anota las fuentes de configuración activas. Esa información será útil si una capa persistente sigue enviando el cliente a Ollama después de intentar volver a la nube.

Para que el cambio dure solo en el terminal actual, configura las variables manualmente. El siguiente ejemplo sigue usando Bash:

read -rs ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL="http://localhost:11434"
claude --model qwen3.5

read -rs acepta la entrada sin mostrarla. Escribe ollama y pulsa Enter. El endpoint compatible de Ollama exige que exista la variable de autenticación, pero el servidor local ignora su valor. ANTHROPIC_BASE_URL dirige las solicitudes al endpoint local, mientras --model qwen3.5 hace explícito el modelo de la prueba y evita depender de un ANTHROPIC_MODEL antiguo o de un valor guardado.

Paso 3: valida lectura, edición y ejecución con un solo archivo

No uses un repositorio de producción como primera prueba. Crea un directorio aislado donde todo resultado sea visible en el archivo, el código de salida y el diff.

mkdir -p claude-ollama-smoke
cd claude-ollama-smoke
git init
cat > total.py <<'PY'
def total(values):
    return sum(values)

if __name__ == "__main__":
    assert total([2, 3]) == 5
PY
git add total.py
python3 total.py

python3 total.py debería terminar con código 0 sin imprimir nada. Inicia Claude Code local desde ese directorio y envíale esta tarea:

Modifica únicamente total.py.
Si algún elemento de values no es int ni float, haz que total lance TypeError con el mensaje exacto numbers only.
En __main__, añade una comprobación para [2, "3"] que confirme el mismo TypeError y el mismo mensaje.
Ejecuta python3 total.py.
No modifiques ningún otro archivo. Muestra el diff al terminar.

La tarea es pequeña a propósito, pero recorre el bucle esencial del agente: leer el archivo, planificar un cambio, invocar la herramienta de edición, solicitar un comando Bash, observar su resultado y presentar el cambio final. Mantén activas las solicitudes de permisos de Claude Code. Que el modelo sea local no convierte en seguro un shell sin restricciones.

Después, ejecuta tú mismo:

python3 total.py
git status --short
git diff -- total.py
ollama ps

Criterios de aceptación:

1. python3 total.py termina con código 0.
2. git status --short solo menciona total.py, y git diff -- total.py contiene únicamente la validación de tipo y la comprobación pedidas.
3. La conversación de Claude Code muestra llamadas a herramientas de archivos y Bash, o solicitudes de permisos, no solo una sugerencia de código en texto.
4. Mientras la tarea está activa, ollama ps lista qwen3.5, CONTEXT es al menos 64000 y PROCESSOR indica si el modelo está completamente en GPU, parcialmente descargado o principalmente en CPU.

Si falla cualquiera de estos puntos, no amplíes todavía el alcance a un repositorio real. Diagnostica primero y decide después si cambias de modelo, reduces la tarea o pasas a la nube.

Paso 4: verifica el límite de ejecución, no solo la URL localhost

ANTHROPIC_BASE_URL=http://localhost:11434 demuestra que Claude Code envía las solicitudes del modelo a un puerto local, pero no prueba que todo el flujo esté desconectado. Una señal más sólida combina un tag sin :cloud, la aparición del modelo en ollama ps durante la tarea y valores locales de PROCESSOR y CONTEXT coherentes con los recursos del equipo.

La FAQ de Ollama indica que Ollama no ve prompts ni datos cuando el modelo se ejecuta localmente, mientras que los prompts y las respuestas de modelos alojados en la nube son procesados por ese servicio. La página actual de Qwen3.5 inicia Claude Code con la etiqueta local qwen3.5. No deduzcas el nombre de un modelo cloud añadiendo un sufijo a una etiqueta local; para comprobar ese límite, usa una etiqueta que el catálogo Cloud o la guía de integración oficial actual indiquen expresamente, como gemma4:cloud. Determina dónde se ejecuta el modelo mediante una etiqueta válida, ollama ps y la asignación local de recursos.

Audita por separado las demás rutas de red:

• Un comando invocado mediante Bash puede acceder a Internet, subir archivos o llamar a otro CLI.
• Un servidor MCP tiene su propio proceso, permisos y ruta de datos.
• Web search, web fetch y los modelos cloud de Ollama no son inferencia local.
• Los hooks, scripts de pruebas y gestores de paquetes del repositorio también pueden contactar servicios externos.

Para un modo de Ollama más estricto y solo local, combina esta clave con el contenido existente de ~/.ollama/server.json sin borrar otras opciones:

{
  "disable_ollama_cloud": true
}

Reinicia Ollama y comprueba que los logs incluyan Ollama cloud disabled: true. Ollama documenta que esto desactiva sus modelos cloud y web search. No audita las conexiones que realicen Claude Code, los servidores MCP o los comandos de shell.

Paso 5: entiende lo que la capa compatible no garantiza

Ollama ofrece una capa compatible con Anthropic Messages API, no una reproducción completa de Anthropic API. La documentación actual incluye messages, streaming, system prompts, imágenes, tool calls, tool results y thinking entre las funciones compatibles, suficientes para formar el bucle básico de Claude Code.

Compatibilidad de protocolo no significa paridad de comportamiento. La calidad al elegir herramientas, la precisión del parche, la estabilidad en tareas largas y el seguimiento de instrucciones dependen del modelo, la cuantización, el contexto asignado y el hardware. Superar la prueba de un archivo demuestra que la ruta mínima funciona en tu entorno; no demuestra que el modelo local iguale a un modelo Claude en un repositorio grande.

Ollama enumera actualmente como no compatibles /v1/messages/count_tokens, prompt caching, Batches API, citations, bloques PDF document y errores server-sent durante streaming. También describe los conteos de tokens como aproximaciones basadas en el tokenizer del modelo. Si tu flujo depende de alguna de estas funciones, conserva una ruta cloud antes de descubrir la carencia en mitad de una tarea.

Paso 6: vuelve a la nube de forma explícita

Si las variables locales solo existen en la sesión actual de Bash, sal de Claude Code y ejecuta:

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY ANTHROPIC_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_OPUS_MODEL
claude

El nuevo proceso podrá seguir tu inicio de sesión habitual o la configuración de un proveedor cloud. Tras arrancar, consulta /status y realiza una pregunta pequeña de solo lectura. Que el cliente se abra no demuestra por sí solo que una solicitud cloud se haya completado.

Si Claude Code sigue conectándose a Ollama, probablemente la redirección esté guardada en settings y no en la shell actual. La referencia oficial de variables de Claude Code indica que un valor env de un archivo de settings reemplaza la misma variable heredada de la shell. Usa /status para identificar las fuentes activas y elimina ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY y los overrides de modelo de la capa correspondiente:

• ~/.claude/settings.json
• .claude/settings.json
• .claude/settings.local.json
• settings administrados por la organización

Cierra por completo y reinicia Claude Code después del cambio. Un valor administrado no puede anularse desde una capa inferior; debe modificarlo un administrador.

Si el modelo local no sirve para la tarea pero quieres seguir usando una API cloud compatible con Anthropic dentro del mismo Claude Code, consulta la guía actual de BetterToken para Claude Code. El Base URL actual es https://bettertoken.ai: no lleva www ni /v1. Copia primero el Model ID exacto desde model plaza. La configuración manual actual usa ANTHROPIC_MODEL para el modelo principal y las tres variables ANTHROPIC_DEFAULT_*_MODEL para los alias Haiku, Sonnet y Opus. En una prueba controlada puedes apuntar las cuatro variables al mismo ID exacto. Esta sesión temporal de Bash evita guardar la API Key en el historial:

read -rsp "BetterToken API Key: " ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
read -rp $'\nBetterToken Model ID: ' ANTHROPIC_MODEL
export ANTHROPIC_MODEL
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
export API_TIMEOUT_MS="3000000"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
claude

El primer aviso oculta la entrada de la API Key; en el segundo, pega el Model ID exacto copiado desde model plaza. Esta prueba apunta el modelo principal y los tres alias al mismo ID. Si necesitas modelos distintos según el rol, asigna a cada variable predeterminada su ID exacto. No añadas /v1 al Base URL. Después de cambiar settings persistentes, cierra por completo y reinicia Claude Code; en una sesión temporal, cierra también el proceso anterior antes de ejecutar este bloque. Por último, envía una solicitud corta y de solo lectura. Considera completado el cambio solo si responde normalmente sin errores 401, de conexión o de modelo y /status muestra la fuente activa esperada; esto no implica paridad total entre las rutas local y cloud.

Diagnóstico de los fallos más habituales

ConnectionRefused o falta de respuesta de localhost:11434

Comprueba que el proceso de Ollama esté activo y que el endpoint use el puerto esperado. Inícialo con ollama serve cuando sea necesario. Si el puerto está ocupado, localiza la instancia existente en vez de crear otra. Antes de reabrir Claude Code, confirma que curl http://localhost:11434/api/ps devuelve JSON.

El chat responde, pero Claude Code no lee ni edita archivos

Llama de nuevo a /api/show y verifica que el modelo anuncie tools. Después observa si Claude Code solicita permisos. Si el modelo solo escribe “podrías cambiarlo así” y nunca emite una llamada a herramienta, cambia a un modelo marcado explícitamente para tools. Que el campo viaje por el protocolo no garantiza que todos los modelos planifiquen herramientas con fiabilidad.

La sesión es muy lenta o pierde contexto en tareas más largas

Ejecuta ollama ps y revisa PROCESSOR y CONTEXT. Una descarga importante a CPU, menos de 64k o presión de memoria repetida son motivos para reducir la tarea, elegir un modelo más pequeño con tools o usar la nube. No elimines permisos y verificaciones solo para que la interacción parezca más rápida.

Cambiar variables en la shell no cambia endpoint o modelo

Ejecuta /status en Claude Code. Un valor env de settings puede sustituir el de la shell, mientras que --model y /model tienen prioridad sobre ANTHROPIC_MODEL. Limpia la fuente que realmente gana, reinicia por completo y repite una solicitud de solo lectura.

Regla práctica para decidir

Trata Claude Code local como una ruta de ejecución que debe ganarse un alcance mayor, no como un simple interruptor. Confirma tools, asigna al menos 64k de contexto y usa el ejercicio de un archivo para revisar llamadas a herramientas, código de salida, diff y ollama ps. Amplía el trabajo solo cuando esas señales sean estables.

Cuando la tarea supere al equipo, dependa de una función Anthropic no compatible o el modelo local falle de forma repetida con código real, elimina el endpoint local y vuelve a la nube deliberadamente. Una ruta de retorno fiable vale más que obligar a que todo el trabajo de programación permanezca local.