Como instalar Claude Code en Mac y Linux paso a paso (tutorial en espanol 2026)

Disclosure: incluyo un enlace de referido a Claude Code. Si te suscribes, Anthropic me otorga 10 USD de crédito de uso. Este tutorial es independiente del referral: lo escribo porque no existe guía completa en español y Claude Code es la herramienta que uso en producción todos los días.

Respuesta rápida

Para instalar Claude Code en Mac o Linux: 1) Tener Node.js 18+ instalado. 2) Ejecutar npm install -g @anthropic-ai/claude-code. 3) Correr claude en terminal. 4) Autenticar con tu cuenta Anthropic (Claude Max o Pro). 5) Verificar versión con claude --versión. El proceso completo toma 5 a 10 minutos en máquina nueva.

Pre-requisitos

Antes de instalar Claude Code, asegúrate de tener:

  • Node.js versión 18 o superior. Verifica con node --versión en terminal. Si tienes versión menor o no tienes Node, instalar via nodejs.org o usando un versión manager como nvm (recomendado).
  • Cuenta Anthropic con Claude Max o Claude Pro activa. Claude Code requiere suscripción de pago. El trial gratuito de 1 semana está disponible vía referral: link para 1 semana gratis.
  • Terminal con git instalado. Casi todos los Mac y Linux ya lo tienen. Verifica con git --versión.
  • Conexión a internet estable. Claude Code envía requests al modelo de Anthropic; latencia de 1-3 segundos es normal.

Instalación en Mac (macOS Sonoma o Sequoia)

Paso 1. Abrir Terminal (Cmd+Espacio, escribir "Terminal", Enter).

Paso 2. Verificar Node.js:

node --versión
# Debe responder algo como v20.18.0 o superior

Si no tienes Node o la versión es menor a 18, instalar con Homebrew:

brew install node

O instalar nvm (recomendado para gestionar múltiples versiones):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.zshrc
nvm install 20
nvm use 20

Paso 3. Instalar Claude Code globalmente:

npm install -g @anthropic-ai/claude-code

Si npm falla con error de permisos, usar sudo npm install -g @anthropic-ai/claude-code o configurar npm para instalación sin sudo siguiendo la guía oficial de npm.

Paso 4. Verificar instalación:

claude --versión
# Debe responder algo como Claude Code v2.x.x

Paso 5. Primera ejecución y autenticación:

cd ~/proyectos/mi-proyecto-de-prueba
claude

Claude Code abrirá el flujo de autenticación en navegador. Inicia sesión con tu cuenta Anthropic (la misma de claude.ai). Después regresa a la terminal — verás el prompt interactivo de Claude Code.

Instalación en Linux (Ubuntu, Debian, Fedora, Arch)

Paso 1. Abrir terminal y verificar Node.js:

node --versión

Paso 2. Si Node no está instalado o la versión es menor a 18, en Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

En Fedora:

sudo dnf install -y nodejs npm

En Arch:

sudo pacman -S nodejs npm

Paso 3. Instalar Claude Code:

npm install -g @anthropic-ai/claude-code

Si tienes problemas de permisos con npm global, configurar prefix sin sudo:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

Paso 4. Verificar y autenticar igual que en Mac:

claude --versión
cd ~/mi-proyecto
claude

Primera sesión: comandos básicos

Una vez dentro de Claude Code, los comandos esenciales:

  • /help — lista de slash commands disponibles
  • /clear — limpia el contexto de conversación
  • /compact — comprime contexto cuando se acerca al límite
  • /exit o Ctrl+D — salir de la sesión
  • /init — genera un CLAUDE.md con documentación inicial del proyecto
  • /passes — ver tus guest passes (referrals) disponibles

Para pedirle una tarea, simplemente escríbela en lenguaje natural:

Lee package.json y dime qué versión de Express estoy usando

O algo más complejo:

Crea un endpoint Flask /health que retorne JSON con timestamp y status ok, agrégalo a app.py y prueba que funciona con curl

Problemas comunes y soluciones

Error: "claude: command not found" después de instalar

Causa: el directorio donde npm instala globales no está en el PATH. Solución en Mac/Linux:

# Encontrar dónde instaló npm
npm config get prefix
# Agregar al PATH (asumiendo /usr/local)
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Error: "Authentication failed" al ejecutar claude

Causa: cuenta sin Claude Max o Pro activa, o navegador bloqueando OAuth. Solución: verificar suscripción en claude.ai/settings/billing, cerrar otros navegadores, intentar de nuevo.

Latencia alta o timeouts

Causa: conexión inestable o región de red lejana a la infraestructura de Anthropic. Solución: probar con conexión cableada, considerar VPN a región más cercana (EE.UU. este), o configurar timeout más alto en claude.json.

"Permission denied" al hacer edits

Causa: Claude Code en modo confirmación pide aprobar cada tool use. Solución: usar claude --dangerously-skip-permissions solo si confías en el flujo (en sesiones de exploración usar el modo seguro).

Configuración avanzada recomendada

Después de la primera sesión, configurar:

  1. CLAUDE.md en la raíz de cada proyecto — documenta reglas específicas del proyecto que Claude Code va a recordar entre sesiones. Ejecutar /init dentro del proyecto para generar uno base.
  2. Permisos automáticos para comandos seguros — editar ~/.claude/settings.json y agregar a la lista de "allow" comandos read-only que usas frecuentemente.
  3. MCP servers para integraciones externas — añadir servidores MCP para herramientas como Chrome DevTools, Telegram, calendar. Ver claude mcp list para opciones disponibles.
  4. Sub-agents personalizados — crear archivos en ~/.claude/agents/ con instrucciones específicas para tareas recurrentes (debug, security review, deploy check).

Cuándo NO instalar Claude Code

Para honestidad técnica, si caes en alguno de estos casos, mejor evaluar otras opciones:

  • Eres developer junior sin experiencia con git/CLI/docker. La curva es alta.
  • Tu equipo prohíbe enviar source code a APIs externas (compliance). Usar Aider con modelos locales.
  • Solo necesitas autocomplete dentro del IDE. Copilot es más eficiente.
  • Presupuesto ajustado donde 100-200 USD/mes no se justifica. Aider con OpenRouter+DeepSeek puede ser alternativa más barata.

Conclusión

Instalar Claude Code en Mac o Linux toma 5-10 minutos en máquina nueva, asumiendo Node.js 18+ y una cuenta Anthropic activa. La curva de aprendizaje real está en aprender el flujo agéntico (delegar tareas multi-paso) más que en la instalación misma.

Si quieres probarlo 1 semana gratis antes de comprometer suscripción: link de referido para 1 semana gratis. Para comparativa técnica con Cursor, Copilot y Aider, ver: Claude Code vs Cursor vs Copilot vs Aider.

— Dr. Irving Varela, Monterrey, Mayo 2026.

Regresar al blog

Deja un comentario