Gemma 4 + Claude Code Router: Claude Code con un modelo local (2026)

Claude Code es la herramienta de programación en terminal de Anthropic, muy valorada por su manejo del contexto y la calidad del código que genera. El problema es que, de fábrica, solo habla con la API en la nube de Anthropic: cada archivo que tocas se sube a sus servidores y cada sesión se cobra contra tu cuenta.

Si te importa la privacidad del código, necesitas trabajar sin conexión o estás dentro de una red corporativa muy restringida, eso es un bloqueo real. Claude Code Router (CCR) es un proxy open source de la comunidad que se sitúa entre Claude Code y la API oficial, y traduce las peticiones hacia un backend compatible con OpenAI, como una instancia local de Ollama ejecutando Gemma 4.

Esta guía recorre la configuración completa: instalar CCR, conectarlo a Gemma 4, probarlo en sesiones reales y, sobre todo, las restricciones legales, técnicas y de soporte que debes aceptar antes de seguir este camino. No estamos vendiendo CCR. Es una solución de zona gris y queremos que decidas con todos los datos.

¿Por qué querrías ejecutar Claude Code sobre un modelo local?

Antes del cómo, el porqué. Tres escenarios legítimos:

Código regulado. Banca, defensa, salud y parte del sector público no pueden enviar código fuente a nubes externas. Los términos de Anthropic no lo resuelven. Un modelo local en la estación de trabajo mantiene el código dentro del perímetro.

Redes malas o aisladas. Teletrabajo con Wi-Fi pésimo, vuelos largos, trabajo de campo, laboratorios seguros. La API en la nube falla; el modelo local sigue respondiendo.

Modelos propios o ajustados. Puede que tengas un Gemma 4 afinado para un dominio (bioinformática, EDA, DSL interno) y quieras la UX de Claude Code encima de tus propios pesos.

Son motivos de ingeniería. «Ahorrar en la factura de Claude» es otra motivación distinta, y este artículo no la defiende.

Aviso legal y de cumplimiento (léelo antes de nada)

Aviso: La configuración que sigue reescribe el endpoint de API de Claude Code para apuntar a un proxy de terceros. Dependiendo de cómo evolucionen los términos de servicio de Anthropic, esto puede violar el acuerdo de uso de Claude Code y poner en riesgo tu cuenta. Este artículo es documentación técnica, no asesoría legal. Si vas a desplegarlo dentro de una empresa, pásalo antes por los equipos legal y de seguridad.

También tendrás que aceptar estos compromisos técnicos:

1. Degradación de funciones. Extended thinking, prompt caching y algunos formatos de tool use están optimizados para modelos de Anthropic. Con Gemma 4 pueden degradarse, comportarse mal o simplemente no activarse.
2. Calidad de salida. Gemma 4 26B / 31B son modelos abiertos muy capaces, pero en razonamiento multi-archivo complejo siguen por debajo de Claude 3.5 / 4. Ajusta expectativas.
3. Proyecto comunitario sin SLA. CCR lo mantienen voluntarios. Si Anthropic cambia el formato de su API, CCR puede romperse de un día para otro y no hay contrato de soporte al que acudir.

Si aceptas esos costes, sigamos.

¿Qué es exactamente Claude Code Router?

CCR es un proxy HTTP local ligero, normalmente escrito en Node.js. Su trabajo es acotado:

1. Escuchar en un puerto local.
2. Aceptar peticiones con el formato de la API Messages de Anthropic.
3. Traducirlas a un formato compatible con OpenAI (Ollama, LiteLLM, OpenRouter, etc.).
4. Devolver la respuesta en streaming con la forma que Claude Code espera.

Lo interesante es la capa de traducción: roles de mensaje, bloques de tool call, deltas de streaming y stop reasons difieren entre ambas familias de API. CCR los normaliza para que Claude Code crea que sigue hablando con Anthropic.

Requisitos previos

• Node.js 18+ (CCR es un proyecto Node)
• Ollama instalado y corriendo (ollama.com)
• Gemma 4 26B o 31B descargado vía Ollama
• Claude Code (npm install -g @anthropic-ai/claude-code)
• Hardware: 26B necesita ~16 GB de RAM; 31B ~24 GB. Ver la guía de hardware al final.

Paso 1: instalar Claude Code Router

Clona el repo e instala dependencias:

git clone https://github.com/<org>/claude-code-router.git
cd claude-code-router
npm install

La URL exacta varía. CCR es comunitario y puede renombrarse o bifurcarse. Busca en GitHub «claude code router» o «claude code proxy» y elige el fork con commits recientes.

Paso 2: apuntar CCR a Ollama

Crea un .env (o config.json, según el fork) dentro del directorio de CCR:

UPSTREAM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=gemma4:26b-a4b
PORT=8082

Arranca el proxy:

npm start

Deberías ver algo como:

Claude Code Router started on port 8082
Upstream: ollama (gemma4:26b-a4b)
Ready to accept connections

Comprobación rápida:

curl http://localhost:8082/v1/models

Deberías recibir un JSON con tu modelo Gemma 4.

Paso 3: redirigir Claude Code hacia CCR

Claude Code lee ANTHROPIC_BASE_URL para decidir a dónde enviar las peticiones. Apúntalo al proxy local:

export ANTHROPIC_BASE_URL="http://localhost:8082"
export ANTHROPIC_API_KEY="local"   # no puede estar vacío; el valor da igual
claude

Claude Code arranca normal, pero todo el tráfico pasa ya por CCR hacia tu Gemma 4 local.

Si no quieres tocar variables cada vez, ponlo en ~/.zshrc / ~/.bashrc, o envuélvelo en un alias para que claude siga usando la API oficial:

alias claude-local='ANTHROPIC_BASE_URL=http://localhost:8082 ANTHROPIC_API_KEY=local claude'

Paso 4: usarlo de verdad

Explicar código:

> Explica qué hace src/auth/middleware.ts

Gemma 4 leerá el archivo y te dará un resumen. Explicaciones razonables en archivos aislados; el razonamiento profundo entre módulos es su punto débil.

Generar un endpoint nuevo:

> Crea src/api/health.ts con un handler GET /api/health que devuelva estado y versión

CRUD y scaffolding HTTP sencillo funcionan bien.

Depurar un fallo:

> npm test falla con "Cannot read properties of undefined". Revisa src/utils/parser.ts

Con una traza clara, Gemma 4 normalmente localiza el problema. Bugs sutiles sin señal de error son mucho más difíciles.

Comparativa honesta de experiencia

Encaja en: generación de código aislada, explicación de código, bugs simples, entornos offline o restringidos.

No encaja en: refactors de arquitectura, ediciones multi-archivo largas, nada que dependa de extended thinking.

CCR frente a otras configuraciones locales

Honestamente: si lo que buscas es «modelo local + programación en terminal», Aider es el camino más maduro. CCR solo tiene sentido si ya estás muy comprometido con Claude Code y tienes una restricción clara de privacidad u offline.

Solución de problemas

«Port already in use» — cambia PORT en .env o mata el proceso que ocupa 8082:

lsof -i :8082
kill -9 <PID>

«Authentication failed» en Claude Code — ANTHROPIC_API_KEY tiene que ser no vacío y ANTHROPIC_BASE_URL debe apuntar al puerto correcto de CCR.

Salida con caracteres raros o truncada — la traducción de CCR no es perfecta. Actualiza (git pull && npm install), prueba con 31B (mejor fidelidad de formato) o simplifica el prompt.

Respuestas lentas — confirma con ollama ps que Ollama está en GPU y considera una cuantización GGUF si vas justo de RAM.

Preguntas frecuentes

¿Anthropic me puede banear la cuenta? El riesgo no es cero. Reescribir el endpoint de API de Claude Code puede violar sus ToS. No damos asesoría legal; trátalo como una decisión de riesgo personal y, para uso comercial, consulta con legal.

¿Gemma 4 sustituye completamente a Claude? No. Claude Code está afinado para capacidades propias de Anthropic (extended thinking, formatos concretos de tool use, manejo profundo de contexto). Gemma 4 te da un subconjunto funcional, no paridad.

¿Funciona en Windows? Sí. Node.js y Ollama son multiplataforma y los pasos son idénticos.

¿Puedo apuntar CCR a GPT-4 u otro modelo en la nube? Sí, CCR soporta varios upstreams, incluido OpenAI. Pero pierdes la privacidad local y sigues pagando los tokens del proveedor.

¿Por qué no usar Aider o Codex CLI directamente? Suele ser la mejor respuesta. Aider está pensado para modelos locales y su repo map más los commits automáticos encajan mejor. Elige CCR solo si la UX de Claude Code es innegociable. Ver la guía Aider + Gemma 4.

¿Sirven Gemma 4 E2B o E4B? Técnicamente sí, en la práctica no. Los 4B / 8B no aguantan cargas agénticas. Mínimo 26B.

¿Puedo usarlo en producción con un equipo? No lo recomendamos. Entre el riesgo de ToS y que CCR depende de un mantenedor comunitario, no lo meteríamos en la ruta crítica de un equipo. Investigación personal o pilotos acotados, vale; producción compartida, mejor no.

Artículos relacionados

• Aider + Gemma 4: la alternativa local más madura
• Gemma 4 con Codex CLI: otra opción orientada a CLI
• Comparativa de CLIs para Gemma 4: Aider vs Codex vs CCR