Instalación y Autenticación de Claude Code

Descripción

Esta cápsula te lleva de cero a tu primera interacción con Claude Code. Vas a instalarlo usando el instalador nativo recomendado por Anthropic, autenticarte, verificar que todo funciona con el comando /doctor, y resolver los problemas más comunes que pueden aparecer en el camino.

No hay atajos aquí. Una instalación limpia y una autenticación sólida son la base de todo lo que viene después. Si algo falla en este paso, cada sesión futura arrastra ese problema. Si todo sale bien — y esta cápsula se asegura de que así sea — Claude Code simplemente funciona cada vez que lo necesitas.

Al final de esta cápsula tendrás Claude Code instalado, autenticado, verificado, y habrás completado tu primera interacción real con el agente.

Requisitos del Sistema

Mínimos obligatorios

Node.js: El instalador nativo maneja las dependencias automáticamente. Solo necesitas Node.js 18+ si vas a usar el SDK programático (Módulo 07).

Verificación previa (macOS/Linux)

# Verifica que puedes ejecutar curl
curl --version

No necesitas instalar nada más antes de proceder.

Instalación de Claude Code

Claude Code ofrece 3 métodos de instalación. El recomendado es el instalador nativo, que se actualiza automáticamente.

Método 1: Instalador nativo (recomendado)

macOS y Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Windows requiere Git for Windows. Instálalo primero si no lo tienes.

Las instalaciones nativas se actualizan automáticamente en segundo plano.

Método 2: Homebrew (macOS)

brew install --cask claude-code

Nota: Homebrew no auto-actualiza. Ejecuta brew upgrade claude-code periódicamente.

Método 3: WinGet (Windows)

winget install Anthropic.ClaudeCode

Nota: WinGet no auto-actualiza. Ejecuta winget upgrade Anthropic.ClaudeCode periódicamente.

El instalador nativo:

• Descarga e instala Claude Code, haciéndolo disponible como comando claude en cualquier directorio
• Configura actualizaciones automáticas en segundo plano
• Típicamente tarda 10-30 segundos dependiendo de tu conexión

Paso 2: Verificar la instalación

claude --version

Resultado esperado:

claude-code v2.x.x

Si ves un número de versión, la instalación fue exitosa.

Paso 3: Primer arranque

claude

La primera vez que ejecutas claude, sucede lo siguiente:

1. Se muestra el banner de bienvenida
2. Se te pide que aceptes los términos de uso
3. Se inicia el flujo de autenticación
4. Una vez autenticado, entras al modo interactivo

╭──────────────────────────────────────────╮
│ Claude Code                              │
│                                          │
│ /help for available commands             │
│ /doctor to check your setup              │
╰──────────────────────────────────────────╯

Autenticación

Opción 1: OAuth (recomendada para uso interactivo)

OAuth es el método más sencillo. Cuando ejecutas claude por primera vez:

1. Claude Code abre tu navegador automáticamente
2. Te lleva a la página de login de Anthropic
3. Inicias sesión con tu cuenta (email + contraseña, o Google/GitHub)
4. Autorizas a Claude Code
5. El navegador confirma la autorización
6. Claude Code en tu terminal detecta la autenticación automáticamente

$ claude
Opening browser for authentication...
✓ Authenticated successfully

Cuándo usar OAuth:

• Uso diario en tu máquina personal
• Cuando tienes un plan Pro o Max
• Es el flujo "normal" para la mayoría de usuarios

Opción 2: API Key (para uso programático)

Si necesitas usar Claude Code de forma no-interactiva (CI/CD, scripts, SDK), la API key es el camino:

1. Ve a console.anthropic.com/settings/keys
2. Crea una nueva API key
3. Configura la variable de entorno:

export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"

Para que persista entre sesiones de terminal:

echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

O en bash:

echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

Cuándo usar API Key:

• Uso en CI/CD (GitHub Actions, GitLab CI)
• Scripts de automatización
• SDK headless
• Cuando no hay navegador disponible (servidores remotos)

Comparación: OAuth vs API Key

La diferencia de billing

Esto es importante y genera confusión:

• OAuth conecta con tu suscripción (Pro, Max 5x, Max 20x). Pagas mensual, tienes un límite de uso incluido.
• API Key conecta con tu crédito API. Pagas por token consumido. No tiene límite mensual fijo — pagas lo que usas.

Puedes tener ambos configurados. Muchos profesionales usan OAuth para su trabajo diario y API key para automatizaciones.

El Comando /doctor

Qué es

/doctor es el comando de diagnóstico de Claude Code. Verifica que todo tu setup esté correcto y reporta problemas si los encuentra.

Cómo ejecutarlo

Hay dos formas:

Desde fuera de Claude Code:

claude doctor

Desde dentro de una sesión interactiva:

> /doctor

Qué verifica

claude doctor chequea tu instalación y configuración, incluyendo:

✓ Authentication           → ¿Estás autenticado?
✓ Network connectivity     → ¿Puede conectar con los servidores de Anthropic?
✓ Model access             → ¿Tienes acceso a los modelos disponibles?
✓ Claude Code version      → ¿Estás en la versión más reciente?
✓ Permissions              → ¿Puede leer/escribir en el directorio actual?

Output esperado (todo bien)

Claude Code Doctor
──────────────────

✓ Authenticated as user@email.com
✓ Network connection OK
✓ Model access: Opus 5, Sonnet 5
✓ Claude Code v2.x.x (latest)
✓ Directory permissions OK

All checks passed!

Output con problemas

Claude Code Doctor
──────────────────

✗ Authentication: No valid credentials found
  → Run 'claude' to authenticate via OAuth
  → Or set ANTHROPIC_API_KEY environment variable
✓ Network connection OK
✗ Model access: Unable to verify (auth required)

2 issues found. Fix authentication to continue.

Cuándo usar /doctor

• Después de instalar — confirma que todo quedó bien
• Cuando algo falla — primera línea de diagnóstico
• Después de actualizar — verifica que la actualización no rompió nada
• En una máquina nueva — setup rápido + verificación
• Cuando cambian los modelos — confirma acceso a los modelos que necesitas

Actualización y Mantenimiento

Actualizar Claude Code

Si usaste el instalador nativo, Claude Code se actualiza automáticamente en segundo plano. No necesitas hacer nada.

Para forzar una actualización manual:

claude update

Verifica la versión:

claude --version

Si usaste Homebrew o WinGet (no auto-actualizan):

# Homebrew
brew upgrade claude-code

# WinGet
winget upgrade Anthropic.ClaudeCode

Cuándo revisar actualizaciones

• Instalación nativa: Las actualizaciones llegan automáticamente
• Homebrew/WinGet: Revisa semanalmente o cuando necesites un feature nuevo
• Inmediato: Cuando Claude Code muestra un mensaje de versión nueva

Troubleshooting

Problema 1: "command not found" después de instalar

Síntoma: zsh: command not found: claude

Causa más común: El binario no está en tu PATH.

# Con instalación nativa, prueba cerrar y reabrir tu terminal
# El instalador agrega claude al PATH automáticamente

# Si persiste, verifica dónde se instaló
which claude

# En macOS/Linux, puede estar en /usr/local/bin/ o ~/.local/bin/

Si usaste Homebrew, verifica que brew está en tu PATH y reinstala.

Problema 2: Errores de permisos

Síntoma: El instalador falla por permisos.

Solución:

# macOS/Linux: el instalador nativo no requiere sudo normalmente
# Si falla, revisa que tu usuario tenga permisos de escritura en /usr/local/bin/

# Si usas Homebrew, este maneja permisos automáticamente
brew install --cask claude-code

Problema 3: Token de autenticación expirado

Síntoma: Authentication error: Token expired or invalid

claude logout
claude
# Fuerza un nuevo flujo de login

Para API key: verifica con echo $ANTHROPIC_API_KEY y reconfigura si está vacía.

Problema 4: Errores de red / proxy

Síntoma: Network error: Unable to connect to Anthropic API

Si estás detrás de un proxy corporativo:

export HTTPS_PROXY="http://proxy.empresa.com:8080"

Claude Code necesita acceso a api.anthropic.com y console.anthropic.com.

Problema 5: Claude Code se instala pero no arranca

Reinstalación limpia:

# macOS/Linux — reinstala con el instalador nativo
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew
brew reinstall --cask claude-code

Walkthrough Completo: De Cero a Primera Interacción

# 1. Instalar Claude Code (instalador nativo)
curl -fsSL https://claude.ai/install.sh | bash

# 2. Verificar instalación
claude --version  # claude-code v2.x.x

# 3. Ejecutar por primera vez
claude
# → Acepta términos de uso
# → Se abre el browser para autenticación
# → Inicia sesión en Anthropic → Autorizar → Volver a terminal

# 5. Verificar setup
> /doctor
# Todos los checks deberían pasar

# 6. Primera interacción real
> ¿Qué archivos hay en este directorio?

# 7. Probar una tarea
> Crea un archivo hello.py que imprima "Claude Code funciona"

# 8. Salir
> /exit

Si cada paso produjo el resultado esperado, tu instalación está completa.

Comparaciones y Decisiones

¿OAuth o API Key?

¿Cómo vas a usar Claude Code?

├─ Uso diario, interactivo, en tu máquina
│  → OAuth (más simple, se renueva solo)
│
├─ CI/CD, scripts, automatización
│  → API Key (no requiere browser)
│
├─ Ambos: uso diario + automatizaciones
│  → OAuth para interactivo + API Key para scripts
│
└─ Servidor remoto sin GUI
   → API Key (no hay browser disponible)

¿Instalación nativa o Homebrew/WinGet?

¿Quieres actualizaciones automáticas?

├─ Sí (recomendado)
│  → Instalador nativo (auto-actualiza en background)
│
└─ No, prefiero controlar las actualizaciones
   → Homebrew o WinGet (actualizas manualmente)

Patterns Comunes

Pattern 1: Setup en máquina nueva

Cuando configuras una máquina nueva o empiezas en una empresa nueva:

curl -fsSL https://claude.ai/install.sh | bash
claude
# Autenticarse
claude doctor
# Verificar todo

2 minutos, setup completo. Sin dependencias previas de Node.js.

Pattern 2: Verificar versión periódicamente

Con instalación nativa, las actualizaciones son automáticas. Verifica que estás al día:

claude --version

Si usaste Homebrew: brew upgrade claude-code periódicamente.

Pattern 3: Verificación rápida antes de sesión importante

Antes de una sesión de desarrollo crítica:

claude doctor

Si todo está verde, adelante. Si algo falla, mejor resolverlo antes de empezar.

Pattern 4: Re-autenticación después de vacaciones

Después de días sin usar Claude Code, tu token puede haber expirado:

claude
# Si pide re-autenticación, sigue el flujo
# Si entra directo, todo bien

Pitfalls y Edge Cases

Pitfall 1: Instalar de forma incorrecta

El instalador nativo recomendado (curl -fsSL https://claude.ai/install.sh | bash) maneja todo automáticamente. Evita métodos de instalación no oficiales o instalar con sudo cuando no es necesario.

Pitfall 2: No verificar con /doctor

"Se instaló, funciona, listo." Hasta que no funciona. /doctor detecta problemas latentes que no son obvios en una interacción simple pero aparecen en uso real.

Pitfall 3: API key hardcodeada en un script commiteado

ANTHROPIC_API_KEY="sk-ant-xxxxx" claude "haz algo"

Si este script se commitea, tu API key queda expuesta. Usa variables de entorno desde .env (que está en .gitignore) o un secret manager.

Pitfall 4: Versión vieja de Claude Code

Claude Code se actualiza frecuentemente. Una versión de hace 2 semanas puede no tener features que la documentación describe. Si algo "debería funcionar pero no funciona", actualiza primero.

Pitfall 5: Confundir instalación nativa con npm (deprecado)

Si antes usabas npm install -g @anthropic-ai/claude-code, migra al instalador nativo: curl -fsSL https://claude.ai/install.sh | bash y luego npm uninstall -g @anthropic-ai/claude-code. El método npm está deprecado.

Pitfall 6: WSL2 con Windows — paths mixtos

En WSL2, mezclar paths de Windows (C:\Users\...) con paths de Linux (/home/...) causa problemas. Trabaja siempre dentro del filesystem de WSL2 (/home/your-user/) para evitar conflictos.

Ejemplo Completo Integrado

Escenario: Setup profesional desde cero en macOS

# 1. Instalar Claude Code (no necesita Node.js)
curl -fsSL https://claude.ai/install.sh | bash

# 2. Verificar
claude --version  # claude-code v2.x.x

# 3. Primer arranque + autenticación
claude
# → Browser flow → Login → Autorizar → Volver a terminal

# 4. Verificar setup completo
> /doctor
# Todos los checks deberían pasar

# 5. Primera tarea real
> ¿En qué directorio estoy y qué archivos hay?
> /exit

Escenario: Setup para CI/CD

# .github/workflows/ci.yml
- name: Claude Code Review
  run: |
    curl -fsSL https://claude.ai/install.sh | bash
    claude -p "Revisa este PR y da feedback" --output-format json
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Escenario: Re-setup después de problemas

# Reinstalar limpio
curl -fsSL https://claude.ai/install.sh | bash
claude logout
claude         # Nuevo flujo de autenticación
> /doctor      # Verificar

Ejercicios Prácticos

Ejercicio 1: Instalación completa

Instala Claude Code siguiendo los pasos de esta cápsula. Verifica cada paso.

Checklist:

• Instalador nativo ejecutado (curl -fsSL https://claude.ai/install.sh | bash)
• claude --version muestra versión
• claude arranca y te autenticas
• /doctor pasa todos los checks

Ejercicio 2: Diagnóstico con /doctor

Ejecuta /doctor y analiza cada línea del output.

1. ¿Estás autenticado? ¿Con OAuth o API key?
2. ¿A qué modelos tienes acceso?
3. ¿Estás en la última versión de Claude Code?

Ejercicio 3: Primera tarea real

Con Claude Code abierto en un directorio de proyecto (o cualquier directorio), ejecuta:

> Explícame la estructura de archivos de este directorio

Evalúa la respuesta: ¿Claude Code pudo leer los archivos? ¿La descripción es precisa?

Ejercicio 4: Simular y resolver un problema

Provoca un error intencionalmente y resuélvelo:

1. Cierra tu sesión: /exit
2. Invalida tu autenticación temporalmente (renombra el archivo de credenciales o cambia la API key)
3. Intenta abrir Claude Code
4. Observa el error
5. Restaura la autenticación y verifica con /doctor

claude logout
claude
# Sigue el flujo de autenticación de nuevo

# Guarda tu key actual
OLD_KEY=$ANTHROPIC_API_KEY

# Invalida la key
export ANTHROPIC_API_KEY="invalid-key"

# Intenta usar Claude Code
claude
# Verás un error de autenticación

# Restaura
export ANTHROPIC_API_KEY=$OLD_KEY

# Verifica
claude doctor

Ejercicio 5: Actualización y verificación

Verifica si hay una versión más nueva de Claude Code y actualiza si es necesario.

claude --version
claude update
claude --version
claude doctor

Resumen

• Instalación: curl -fsSL https://claude.ai/install.sh | bash (nativa, recomendada) o via Homebrew/WinGet
• Autenticación: OAuth para uso interactivo (browser flow), API key para uso programático (variable de entorno)
• Verificación: /doctor es tu herramienta de diagnóstico — úsala después de instalar, actualizar, o cuando algo falla
• Actualización: Automática con instalación nativa, claude update para forzar
• Troubleshooting: Los problemas más comunes son PATH no configurado, permisos, y tokens expirados
• Primer paso siempre: instalador nativo → claude → /doctor
• OAuth vs API key: No son excluyentes — puedes usar ambos para diferentes propósitos
• WSL2 en Windows: Trabaja dentro del filesystem de WSL2, no en paths de Windows

Siguiente cápsula: 03 - Plataformas disponibles — Claude Code no solo vive en la terminal. Descubre dónde más puedes usarlo y cuándo elegir cada plataforma.

Recursos Adicionales

1. Advanced Setup — Requisitos del sistema, instalación por plataforma, actualizaciones, y desinstalación
2. Authentication — Todos los métodos de autenticación (OAuth, API key, third-party providers)
3. Claude Code CLI Reference — Referencia completa de comandos, flags, y opciones
4. Troubleshooting — Soluciones para problemas comunes de instalación y uso
5. Anthropic Console — API Keys — Crear y gestionar API keys
6. Git for Windows — Requerido para instalación nativa en Windows
7. WSL2 Installation Guide — Configurar Windows Subsystem for Linux 2 (opcional en Windows)
8. Claude Code GitHub Discussions — Comunidad y soporte para problemas de instalación