Claude Code con DeepSeek en WSL/Linux: instalación, configuración, pruebas y solución de errores comunes
Aprende a instalar Claude Code en WSL o Linux, dirigirlo a través del endpoint compatible con Anthropic de DeepSeek, verificar la conexión y solucionar errores comunes 401, 403 y 404. Esta guía práctica cubre la instalación con npm, ~/.claude/settings.json, variables de entorno, selección de modelos y una ruta de configuración más segura para desarrolladores que trabajan en regiones restringidas.
Portada de Claude Code con DeepSeek
Si quieres que Claude Code se ejecute dentro de WSL o Linux sin depender del endpoint directo de Anthropic, la ruta más sencilla ahora mismo es apuntarlo a la API compatible con Anthropic de DeepSeek.
Esa es la idea central detrás del tutorial original y, sinceramente, resuelve exactamente el problema con el que muchos desarrolladores siguen encontrándose: Claude Code se instala bien, pero la primera sesión real falla por acceso regional, enrutamiento del endpoint o configuración del modelo.
Así que, en lugar de convertir esto en una vaga “visión general de herramientas de codificación con IA”, mantengámoslo práctico. Haremos cuatro cosas:
Instalar Claude Code en WSL o Linux
Enrutarlo a través de DeepSeek
Probar el endpoint antes de perder tiempo depurando la CLI
Corregir los errores comunes que suelen aparecer primero
Flujo de configuración de Claude Code y DeepSeek
Por qué esta configuración importa
Sobre el papel, Claude Code es simplemente otro asistente de programación basado en terminal. En la práctica, lo que lo hace útil es que puede leer tu repositorio, ejecutar comandos, inspeccionar archivos y mantenerse dentro de un flujo de trabajo de desarrollo real, en lugar de comportarse como una caja de chat que casualmente sabe algo de código.
La fricción empieza cuando empieza la conectividad.
Para los desarrolladores que trabajan en entornos de red restringidos, la ruta predeterminada oficial puede convertirse en el verdadero obstáculo. Por eso el enfoque con DeepSeek resulta atractivo: mantienes el flujo de trabajo de Claude Code, pero cambias la ruta del backend a un endpoint compatible con Anthropic que DeepSeek expone.
Aquí también es donde la guía se vuelve más útil que una publicación aleatoria de “copia estos comandos”. La diferencia entre una configuración que parece correcta y una que realmente funciona suele depender de:
qué variables de entorno configuras
dónde las haces persistentes
qué nombre de modelo usas
si pruebas el endpoint antes de iniciar claude
Paso 1: Instalar Claude Code en WSL o Linux
El artículo original usa la ruta de instalación basada en npm, y sigue funcionando bien cuando ya tienes Node preparado en WSL o Linux.
Si tu red es inestable, cambia primero al registro oficial de npm, instala Claude Code globalmente y luego vuelve a tu mirror habitual:
# Cambiar al registro oficial de npm
npm config set registry https://registry.npmjs.org
# Instalar Claude Code globalmente
npm install -g @anthropic-ai/claude-code
# Volver a tu mirror preferido
npm config set registry https://registry.npmmirror.com
Si tu red funciona bien, la versión corta es suficiente:
npm install -g @anthropic-ai/claude-code
Después confirma la instalación:
claude --version
Si obtienes un número de versión, la CLI en sí está instalada correctamente. Eso no significa que el endpoint del modelo ya esté listo, pero sí significa que el paso de instalación local está completado.
Una nota rápida sobre la ruta de instalación oficial
La documentación actual de Anthropic también recomienda un instalador nativo para macOS, Linux y WSL:
curl -fsSL https://claude.ai/install.sh | bash
Esa es hoy la ruta más “oficial”, pero para los desarrolladores que ya usan herramientas basadas en Node dentro de WSL, la ruta con npm sigue siendo perfectamente razonable y encaja limpiamente con el flujo de trabajo del artículo original.
Paso 2: Preparar el directorio de configuración de Claude
La publicación original señala una molestia muy real: a veces intentas editar la configuración local de Claude Code y te encuentras de inmediato con un muro de permisos.
Si vim u otro editor no puede escribir en ~/.claude, corrige primero la propiedad y los permisos:
mkdir -p ~/.claude
chown -R "$USER":"$USER" ~/.claude
chmod -R 755 ~/.claude
No es algo glamuroso, pero ahorra tiempo. Una cantidad sorprendente de “problemas de configuración de Claude Code” son en realidad problemas de permisos de archivos.
Paso 3: Apuntar Claude Code a DeepSeek
Hay dos formas sensatas de hacerlo:
variables de entorno temporales del shell
un ~/.claude/settings.json persistente
El artículo fuente usa el segundo enfoque y, para un uso repetido, creo que es la mejor configuración cotidiana.
Abre el archivo de configuración:
vim ~/.claude/settings.json
Luego pega una configuración mínima funcional como esta:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
"ANTHROPIC_AUTH_TOKEN": "your-deepseek-api-key",
"ANTHROPIC_MODEL": "deepseek-v4-flash",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-flash"
}
}
Eso refleja el espíritu de la guía original: simple, persistente y suficiente para ponerse en marcha.
Una versión más completa basada en la documentación más reciente de DeepSeek
La documentación oficial de integración de DeepSeek con Claude Code ahora muestra una configuración más completa con valores predeterminados separados para Opus, Sonnet, Haiku, subagentes y nivel de esfuerzo. Si quieres una configuración más completa, usa esta:
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
"ANTHROPIC_AUTH_TOKEN": "your-deepseek-api-key",
"ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
"CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash",
"CLAUDE_CODE_EFFORT_LEVEL": "max"
}
}
¿Qué modelo deberías usar realmente?
Esta es la regla simple:
Usa deepseek-v4-flash si quieres menor coste y programación cotidiana más rápida
Usa deepseek-v4-pro[1m] si quieres razonamiento más sólido y trabajo más exigente con contextos largos
Si solo quieres que la primera configuración funcione, empieza con Flash. Una vez que el flujo sea estable, puedes pasar a Pro para tareas más difíciles.
Paso 4: Prueba el endpoint antes de iniciar Claude Code
Este paso es opcional en teoría, pero en la vida real te evita tener que adivinar.
Antes de iniciar la CLI, llama directamente al endpoint compatible con Anthropic de DeepSeek:
curl -X POST https://api.deepseek.com/anthropic/v1/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-deepseek-api-key" \
-d '{
"model": "deepseek-v4-flash",
"max_tokens": 10,
"messages": [
{
"role": "user",
"content": "test"
}
]
}'
Si recibes una respuesta JSON normal, tu endpoint y tu clave están activos.
Eso importa porque separa dos tipos de fallos:
Problemas de enrutamiento de la API
Problemas de la CLI de Claude Code
Si la prueba con curl ya falla, no pierdas tiempo culpando a la CLI.
Paso 5: Inicia Claude Code
Una vez que la instalación y la prueba del endpoint hayan pasado, inicia Claude Code normalmente:
claude
En ese momento, la experiencia debería sentirse casi normal desde el lado de la CLI. La principal diferencia es simplemente que el tráfico del modelo ahora se enruta a través de la interfaz compatible con Anthropic de DeepSeek.
Los errores que es más probable que veas
Aquí es donde la mayoría de los “tutoriales de configuración” se vuelven demasiado educados y dejan de ser útiles, así que seamos directos.
1. E212: No se puede abrir el archivo para escribir
Normalmente esto no es un problema de Claude. Es un problema de permisos del sistema de archivos.
Solución:
mkdir -p ~/.claude
chown -R "$USER":"$USER" ~/.claude
chmod -R 755 ~/.claude
2. No se puede conectar con los servicios de Anthropic o 403 Forbidden
Normalmente esto significa que Claude Code sigue intentando usar la ruta predeterminada, o que la configuración de tu endpoint es incorrecta.
Comprueba que:
ANTHROPIC_BASE_URL sea exactamente `https：//api.deepseek.com/anthropic`
tu archivo de configuración sea JSON válido
no hayas guardado accidentalmente el archivo en la ruta equivocada
3. 401 Unauthorized
Casi siempre es una de estas causas:
la clave de API es incorrecta
la clave se copió con espacios o comillas adicionales
la cuenta de DeepSeek tiene un problema de facturación o saldo
No le des demasiadas vueltas a esto. 401 suele ser un problema de clave, no un problema de modelo.
4. 404 Not Found
Esto suele ser un error en el nombre del modelo o en la ruta.
Empieza comprobando:
ruta del endpoint：https://api.deepseek.com/anthropic
ruta de solicitud para pruebas：/v1/messages
cadena del modelo：deepseek-v4-flash o deepseek-v4-pro[1m]
Si escribiste un nombre de modelo antiguo o mal formado, la solicitud puede fallar aunque todo lo demás sea correcto.
Un mejor modelo mental para esta configuración
La forma más útil de pensar en esto no es “estoy hackeando Claude Code”.
Es más parecido a esto:
Claude Code es el flujo de trabajo del frontend. DeepSeek es la ruta del modelo en el backend.
Una vez que lo ves de esa manera, la configuración se vuelve más fácil de depurar:
si claude --version falla, es un problema de instalación
si la prueba con curl falla, es un problema de ruta de API o de autenticación
si ambas cosas funcionan pero la sesión sigue fallando, es un problema de configuración del lado de Claude
Solo esa separación puede ahorrar mucho ensayo y error innecesario.
Qué ha cambiado desde los tutoriales anteriores
Vale la pena destacarlo porque el ecosistema sigue avanzando.
El tutorial original se centra en una configuración mínima funcional y usa settings.json junto con deepseek-v4-flash, lo cual sigue siendo útil. Pero la documentación oficial más reciente añade algunos detalles que aclaran mejor el panorama completo:
Claude Code ahora tiene un instalador nativo oficial en la documentación de Anthropic
DeepSeek tiene una guía explícita de integración con Claude Code
DeepSeek documenta la asignación de modelos para familias de modelos de estilo Claude
el conjunto completo recomendado de variables de entorno es más amplio que los fragmentos antiguos de la comunidad
Así que, si estás reescribiendo tus propias notas de configuración, no congeles la guía en la primera configuración que dio la casualidad de funcionar una vez. Mantén la estructura, pero actualiza los detalles.
Dónde encaja We0 AI
Si estás creando con herramientas como Claude Code, DeepSeek, WSL y flujos de trabajo centrados en la terminal, hay un segundo problema que suele aparecer justo después de la configuración:
puedes construir la solución, pero tu sitio web aún no la explica con la suficiente claridad como para atraer a los usuarios adecuados.
Ese es exactamente el espacio para el que se creó We0 AI.
We0 AI ayuda a fundadores, creadores, consultores, agencias y equipos técnicos a crear sitios web de presentación que expliquen qué hace su producto, posicionen en buscadores y conviertan la curiosidad en clientes potenciales. En otras palabras, no se trata solo de “poner una página en línea”, sino de hacer que el producto sea realmente comprensible y fácil de encontrar.
Así que, si tu stack está mejorando pero tu distribución sigue siendo caótica, ese es el siguiente cuello de botella que debes solucionar.
Conclusión
El artículo original acierta en algo importante: el avance no es instalar Claude Code en sí, sino hacer que toda la ruta sea utilizable en un flujo de trabajo real de WSL/Linux.
Si quieres el camino más corto:
instala Claude Code
configura el endpoint compatible con Anthropic de DeepSeek
guarda tu clave de forma segura
prueba primero la API
después inicia claude
Ese es todo el juego.
Y si algo falla, no entres en pánico ni reinstales todo. En la mayoría de los casos, el problema es solo una de estas cuatro cosas: permisos, ruta del endpoint, clave de API o nombre del modelo.
Referencias
Descripción general de Claude Code
Guía de integración de DeepSeek con Claude Code
Guía de la API Anthropic de DeepSeek
Artículos y herramientas relacionados