Claude Code con OpenRouter y DeepSeek no empieza con una línea de configuración, sino con una decisión de ruta. OpenRouter tiene sentido cuando OpenRouter debe ser dueño del gateway, del catálogo de modelos, del enrutamiento de proveedores y del registro de actividad. DeepSeek directo tiene sentido cuando Claude Code debe hablar con el endpoint Anthropic-compatible de DeepSeek, usando token, modelo y actividad de DeepSeek. Un proxy o router de terceros debe tratarse como una ruta experimental hasta que demuestre forma de API, logs, coste y ruta de datos.
| Ruta | Cuándo usarla | Qué debe coincidir antes de probar |
|---|---|---|
| OpenRouter | Quieres que OpenRouter controle gateway, provider routing, catálogo y actividad. | Base URL de OpenRouter, token de OpenRouter, modelo de OpenRouter y actividad en OpenRouter. |
| DeepSeek directo | Quieres enviar Claude Code al API Anthropic-compatible de DeepSeek. | Base URL de DeepSeek, token de DeepSeek, model ID de DeepSeek y actividad en DeepSeek. |
| Proxy/router | Estás probando un adapter, gateway local o router de equipo. | Un solo owner explica base URL, token, model mapping, logs, data handling y prueba de coste. |
Antes del primer trabajo real en un repositorio, detente si /status, los logs del proveedor y un canary prompt pequeño no apuntan al mismo owner. Una prueba debe tener una sola base URL, un solo dueño de credenciales y un solo dueño de modelo. Si no coinciden, vuelve atrás antes de añadir más ajustes.
Primero la ruta, después las variables
El fallo común no es que falte un comando secreto de Claude Code. El fallo común es mezclar rutas: una base URL de OpenRouter con un token de DeepSeek, un model ID de DeepSeek mientras una sesión antigua de Anthropic sigue ganando, o un proxy que acepta una llamada pero no conserva la forma Anthropic API que Claude Code espera.
Con la revisión del 3 de julio de 2026, la frontera útil queda así:
| Owner | Qué controla | Qué no prueba |
|---|---|---|
| Anthropic Claude Code docs | Comportamiento del cliente, nombres de variables, settings, /status, frontera de gateway. | Que todos los modelos o proxies de terceros estén soportados por Anthropic. |
| OpenRouter docs | Ruta de Claude Code en OpenRouter, token, base URL, nombres de modelo, actividad del proveedor. | Que DeepSeek directo se comporte igual que OpenRouter routing. |
| DeepSeek docs | Endpoint Anthropic-compatible de DeepSeek, model IDs, mapping y caveats. | Que OpenRouter routing o un proxy ya estén activos. |
| Proxy/router project | Su adapter, logs, coste, ruta de datos y claims de compatibilidad. | Soporte oficial de Claude Code, precios de proveedor o comportamiento de tools. |
El cookbook de OpenRouter sirve cuando OpenRouter es el dueño del gateway. La documentación de DeepSeek sirve cuando DeepSeek directo es el dueño de la ruta. La documentación de Anthropic sigue definiendo la frontera del cliente Claude Code. Mezclarlas sin elegir owner convierte la depuración en adivinanza.
Limpia credenciales en conflicto
Antes de configurar, revisa el shell actual. No imprimas secretos; solo verifica si una variable existe:
test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set"
test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set"
test -n "$ANTHROPIC_BASE_URL" && echo "ANTHROPIC_BASE_URL is set"
test -n "$ANTHROPIC_MODEL" && echo "ANTHROPIC_MODEL is set"
Si el resultado sorprende, busca la fuente: shell profile, loader de .env, terminal del IDE, devcontainer, secreto de CI o .claude/settings.local.json. Poner otro export encima puede parecer rápido, pero luego nadie sabe qué credencial ganó.
Para una prueba limpia:
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_MODEL
Inicia Claude Code desde el mismo shell que acabas de revisar. La prueba solo vale si el entorno inspeccionado y el proceso que arranca Claude Code son el mismo camino.
Configuración con OpenRouter
Usa OpenRouter cuando OpenRouter debe ser dueño del gateway. El token viene de OpenRouter, la base URL apunta a OpenRouter, el selector de modelo sigue la documentación actual de OpenRouter y la actividad aparece en OpenRouter.
Prueba temporal de shell:
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
unset ANTHROPIC_API_KEY
claude
/status
En documentos y scripts compartidos usa placeholders, nunca claves reales. La regla importante es que ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN y el modelo pertenecen a la misma ruta OpenRouter.
La primera prueba debe ser aburrida: sesión nueva de Claude Code, /status, canary prompt sin editar archivos y actividad coincidente en OpenRouter. Si el estado local y el activity log no coinciden, no cambies modelos al azar. Limpia el entorno y reconstruye la ruta desde un solo owner.
Configuración con DeepSeek directo
Usa DeepSeek directo cuando quieres que Claude Code envíe requests Anthropic-compatible al API de DeepSeek. DeepSeek es dueño del endpoint, token, model IDs, caveats de compatibilidad y actividad del proveedor.
Prueba de shell:
export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="$DEEPSEEK_API_KEY"
export ANTHROPIC_MODEL="deepseek-v4-pro[1m]"
claude
/status
La documentación de DeepSeek también lista opciones para coding agents como deepseek-v4-flash. No trates esos IDs como permanentes. Disponibilidad, sufijos, comportamiento de web search, mapping y precio son datos volátiles; revísalos antes de fijarlos en un runbook.
Un log de OpenRouter no prueba DeepSeek directo. Prueba una ruta de OpenRouter que quizá usa DeepSeek como proveedor. Para DeepSeek directo necesitas endpoint de DeepSeek, modelo de DeepSeek y actividad de DeepSeek.
settings.local para evitar drift
Los exports de shell sirven para un canary. No son buenos cuando vuelves dos días después y no recuerdas qué terminal poseía la ruta. Para experimentos repetibles, usa un local settings ignorado por git.
Forma de DeepSeek directo:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
"ANTHROPIC_AUTH_TOKEN": "$DEEPSEEK_API_KEY",
"ANTHROPIC_MODEL": "deepseek-v4-flash"
}
}
Forma de OpenRouter:
{
"env": {
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
"ANTHROPIC_AUTH_TOKEN": "$OPENROUTER_API_KEY",
"ANTHROPIC_MODEL": "openrouter-model-id-from-current-docs"
}
}
No lo pegues sin más en .claude/settings.json. Confirma primero que .claude/settings.local.json está ignorado. Tokens, base URLs privadas y elecciones personales de proveedor pertenecen al ámbito local.
Verificación antes de trabajo real
Verificar no es limpieza posterior; es parte de la configuración. Un cambio de backend solo es seguro cuando route, credential, model y provider evidence coinciden.
| Paso | Qué revisar | Condición de paso |
|---|---|---|
| 1. Minimal prompt | Prompt pequeño sin editar el repositorio. | Responde sin errores de auth o tools. |
2. /status | Cuenta, ruta y modelo vistos por Claude Code. | Coinciden con el owner elegido. |
| 3. Environment | Base URL, dueño de token, variable de modelo. | Solo quedan variables de la ruta activa. |
| 4. Provider activity | Dashboard o log de OpenRouter o DeepSeek. | El request aparece bajo el owner correcto. |
| 5. Repo action de solo lectura | Leer configuración, resumir scripts, comando inocuo. | No modifica archivos y el comportamiento es normal. |
| 6. Rollback | Limpiar variables y reiniciar. | La sesión vuelve a una ruta conocida. |
No omitas provider activity cuando el motivo del cambio es coste, disponibilidad o elección de modelo. /status muestra lo que cree el cliente; la actividad del proveedor muestra quién recibió el request.
Clasifica el primer error
Cuando falla el primer run, clasifica antes de sumar ajustes. La mayoría de intentos rotos son ownership mismatch.
| Síntoma | Causa probable | Primer arreglo |
|---|---|---|
401 o 403 | Token de otro owner, clave expirada o variable equivocada ganando prioridad. | Limpiar variables, configurar un solo token owner y reiniciar. |
404, model not found, model mismatch | Model ID de otra ruta o catálogo viejo. | Usar el ID actual del route owner y verificar actividad. |
| Dashboard silencioso | El request no llegó al proveedor esperado. | Revisar ANTHROPIC_BASE_URL, fuente del shell, login antiguo o proxy. |
| Claude Code se cuelga o tools raras | Proxy parcial, headers no preservados o tool flow incompatible. | Volver a una ruta documentada y probar el proxy aparte. |
| Coste en el lugar equivocado | Route owner y billing owner se mezclaron. | Usar /status más actividad antes de seguir. |
| Ruta free/unlimited falla | El claim no tiene proof actual del proveedor. | Tratarlo como marketing no verificado hasta tener ruta, modelo y límites. |
Patrón rápido de recuperación:
unset ANTHROPIC_AUTH_TOKEN
unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset ANTHROPIC_MODEL
claude
/status
Después de volver a un estado conocido, añade solo una rama. Si falla OpenRouter, depura base URL, token, modelo y activity de OpenRouter. Si falla DeepSeek directo, depura endpoint, token, model ID y activity de DeepSeek. No mezcles correcciones entre ramas hasta que una pase el canary.
Coste, datos y soporte: reglas de parada
El primer valor no es prometer coste bajo. El primer valor es una ruta demostrable. Precios, free tiers, prioridad de proveedor, cargos de web search, disponibilidad de modelos y rate limits cambian rápido. Cualquier promesa de free forever, unlimited, 2-5% más barato o any model necesita prueba actual del owner.
| Regla | Por qué importa |
|---|---|
| No enviar código sensible por un proxy no verificado | No sabes quién registra prompts, archivos o tool output. |
| No creer un claim de coste sin proof de proveedor | OpenRouter y DeepSeek pueden cambiar precios y disponibilidad. |
| No llamar soporte oficial de Anthropic a una ruta non-Claude | Anthropic define la frontera del cliente Claude Code, no cada gateway result. |
| No commitear tokens ni base URLs privadas | Shared settings no son almacenamiento de secretos. |
| No ejecutar ediciones reales sin provider activity proof | Necesitas rollback antes de que un agent cambie archivos. |
Si el problema real es elegir gateway, compara gateways. Si es instalar CLI, empieza por instalación. Si DeepSeek se usa en otro producto, no arrastres esa ruta de producto a la configuración gateway de Claude Code.
Preguntas frecuentes
¿Claude Code puede usar OpenRouter y DeepSeek?
Sí, pero no como una ruta mezclada. Una sesión debe pertenecer a OpenRouter, DeepSeek directo o un proxy owner. Base URL, token, modelo y activity proof deben apuntar al mismo owner.
¿DeepSeek por OpenRouter o DeepSeek directo?
Usa OpenRouter si quieres provider routing, dashboard, catálogo de modelos y comportamiento gateway de OpenRouter. Usa DeepSeek directo si necesitas endpoint Anthropic-compatible de DeepSeek, model IDs de DeepSeek y actividad de DeepSeek. La mejor ruta es la que puedes demostrar para tu repositorio, coste y soporte.
¿Dónde deben vivir los settings?
Shell variables para un canary. .claude/settings.local.json ignorado por git para experimentos locales repetibles. No pongas tokens, base URLs privadas ni elección personal de ruta en settings compartidos.
¿Qué prueba /status?
Es el primer check del cliente. Ayuda a ver qué ruta cree activa Claude Code, pero no basta. Combínalo con environment check y activity de OpenRouter o DeepSeek antes de trabajo real.
¿Puedo usar una ruta gratis o ilimitada?
Solo si la ruta actual del proveedor lo demuestra. Free tier, unlimited, prioridad y pricing son datos volátiles. Un runbook publicable debe tener fecha de prueba, owner y rollback path.
¿Por qué falla el nombre del modelo?
Puede pertenecer a otro owner. Un nombre de modelo de OpenRouter, un ID directo de DeepSeek y un alias de Anthropic no son intercambiables. Limpia la ruta, elige un owner y valida contra su documentación actual.