Cómo Instalar Claude Code: Guía para Mac, Windows y Linux

Resumen: Claude Code se instala como un paquete npm en menos de 5 minutos en Mac, Windows o Linux. Necesita Node.js 18+ y acceso activo a FreeClaude. Esta guía cubre la instalación para cada plataforma, la configuración posterior a la instalación, su primera sesión, los comandos esenciales y la resolución de problemas comunes.

¿Qué es Claude Code?

Claude Code es el asistente de programación de IA basado en terminal de Anthropic, y es categóricamente diferente de las herramientas de IA basadas en navegador o los complementos de IDE. En lugar de pegar fragmentos de código en una ventana de chat y aplicar cambios manualmente, Claude Code opera directamente en su terminal con acceso completo a su sistema de archivos, comandos de shell y herramientas de desarrollo.

Esto significa que Claude Code puede:

• Leer toda la estructura de su proyecto y comprenderla antes de realizar cualquier cambio
• Crear, modificar y eliminar archivos directamente en su máquina
• Ejecutar su suite de pruebas, ver los errores y corregirlos automáticamente
• Ejecutar comandos git, herramientas de compilación y cualquier comando de shell
• Realizar cambios coordinados en docenas de archivos en una sola sesión
• Crear commits con mensajes significativos que explican el razonamiento detrás de los cambios

Para los desarrolladores profesionales, esto transforma la IA de un asistente de copiar y pegar en un verdadero socio de desarrollo autónomo. Las funciones que antes llevaban una tarde ahora pueden implementarse en 20 minutos a través de las sesiones agénticas de Claude Code.

Requisitos Previos

Antes de instalar Claude Code, asegúrese de tener lo siguiente:

Si aún no tiene acceso activo a FreeClaude, visite freeclaude.io y complete su primer referido para desbloquear las descargas. El sistema de referidos es la única forma de acceder a Claude Code a través de FreeClaude.

Instalación en macOS

Paso 1: Instalar Node.js (si es necesario)

Abra Terminal (presione Cmd + Espacio, escriba "Terminal", presione Intro). Compruebe si Node.js ya está instalado:

node --version

Si ve un número de versión inferior a 18.x o ve "command not found", instale Node.js usando fnm (Fast Node Manager) — el enfoque recomendado:

curl -fsSL https://fnm.vercel.app/install | bash

Cierre y vuelva a abrir Terminal, luego ejecute:

fnm install --lts

Verificación: node --version debería mostrar 20.x o superior.

Paso 2: Instalar Claude Code

Con Node.js listo, instale Claude Code globalmente a través de npm:

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

Alternativamente, puede descargar el binario precompilado directamente desde la pestaña Descargas en su panel de FreeClaude. El enfoque de binario no requiere Node.js pero ofrece menos flexibilidad para las actualizaciones.

Paso 3: Autenticarse

Ejecute claude en su terminal. En el primer lanzamiento, le pedirá que se autentique con sus credenciales de FreeClaude. Siga las instrucciones en pantalla: normalmente se abre una ventana del navegador para la autenticación OAuth, o pega un token desde su panel.

Apple Silicon (M1/M2/M3/M4) vs Intel

El método de instalación npm funciona de forma idéntica en ambas arquitecturas: npm detecta su chip e instala el binario correcto automáticamente. El enfoque de binario precompilado proporciona descargas separadas para Apple Silicon e Intel; su panel sirve automáticamente la versión correcta según la detección de su dispositivo.

Instalación en Windows

Paso 1: Instalar Node.js

Abra PowerShell como Administrador (haga clic derecho en el botón Inicio, seleccione "Windows PowerShell (Administrador)").

Compruebe si tiene Node.js: node --version

Si no está instalado, use winget (integrado en Windows 10/11):

winget install -e --id OpenJS.NodeJS.LTS --accept-source-agreements --accept-package-agreements

Cierre PowerShell completamente y vuelva a abrirlo como Administrador. Verificación: node --version

Paso 2: Instalar Claude Code

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

Si encuentra un error de política de ejecución de PowerShell, ejecute esto primero:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Paso 3: Recomendación de Terminal de Windows

Para la mejor experiencia con Claude Code en Windows, use Windows Terminal (disponible gratuitamente en Microsoft Store) con PowerShell 7. El símbolo del sistema clásico funciona pero tiene limitaciones de visualización para el formato de salida enriquecida de Claude Code.

WSL (Subsistema de Windows para Linux) también funciona bien si prefiere un entorno de desarrollo similar a Linux en Windows.

Instalación en Linux

La instalación en Linux suele ser la más sencilla, ya que la mayoría de las máquinas de desarrollo ya tienen Node.js y un terminal capaz.

Ubuntu/Debian

Compruebe la versión de Node.js: node --version

Si está por debajo de 18 o falta, instale a través de NodeSource:

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

Luego instale Claude Code: sudo npm install -g @anthropic-ai/claude-code

Fedora/RHEL/CentOS

curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
sudo dnf install -y nodejs
sudo npm install -g @anthropic-ai/claude-code

Arch Linux

sudo pacman -S nodejs npm
sudo npm install -g @anthropic-ai/claude-code

Cualquier Linux (a través de fnm)

curl -fsSL https://fnm.vercel.app/install | bash
Reinicie su shell, luego:
fnm install --lts
npm install -g @anthropic-ai/claude-code

Configuración Post-Instalación

Después de instalar, complete estos pasos antes de su primera sesión de programación:

1. Abra una nueva ventana de terminal — Esto es importante. Las nuevas entradas de PATH añadidas por la instalación de npm solo tienen efecto en nuevas sesiones de terminal.
2. Verificar la instalación — Escriba claude --version y confirme que aparece un número de versión.
3. Ejecutar la autenticación inicial — Escriba claude y siga las instrucciones de autenticación. Esto conecta Claude Code a su cuenta de FreeClaude.
4. Configurar git (si aún no está hecho) — Claude Code crea commits en su nombre. Asegúrese de que git conozca su identidad: git config --global user.name "Su Nombre" y git config --global user.email "usted@ejemplo.com"

Su Primera Sesión con Claude Code

Navegue a un proyecto en el que esté trabajando e inicie Claude Code:

cd ~/mi-proyecto
claude

Claude Code se inicia y muestra los detalles de su cuenta y el estado del acceso. Para su primera sesión, pruebe estos prompts introductorios:

• "Lee este proyecto y dame un resumen de la arquitectura, los componentes principales y cualquier problema inmediato que notes"
• "Muéstrame la cobertura de pruebas e identifica las áreas sin pruebas"
• "Encuentra cualquier comentario TODO o sentencia console.log que haya quedado en el código"
• "¿Qué dependencias están desactualizadas y cuáles actualizaciones serían seguras de aplicar?"

Estos prompts dan a Claude Code la oportunidad de familiarizarse con su proyecto antes de pedirle que realice cambios, lo que generalmente produce mejores resultados que pasar directamente a modificaciones del código.

Referencia de Comandos Esenciales

Configuración y Personalización

Claude Code lee un archivo CLAUDE.md desde la raíz de su proyecto si existe. Este archivo actúa como un conjunto de instrucciones persistente que Claude Code carga al inicio de cada sesión en ese proyecto. Puede usarlo para especificar:

• Convenciones del proyecto, patrones de nomenclatura y preferencias de estilo de código
• Requisitos de prueba y expectativas de cobertura
• Procedimientos de implementación y notas de infraestructura
• Contexto específico del equipo del que Claude siempre debe estar al tanto
• Rutas de archivos que no deben modificarse

Ejecute /init en cualquier proyecto para que Claude Code genere automáticamente un CLAUDE.md inicial basado en su análisis de su base de código. Revíselo y refínelo antes de confirmarlo.

Solución de Problemas

"command not found: claude"

Cierre y vuelva a abrir su terminal. Si el problema persiste, compruebe que el directorio bin global de npm esté en su PATH:

npm config get prefix

Añada la ruta de salida con /bin anexado a su perfil de shell (~/.zshrc, ~/.bashrc o equivalente).

"Authentication failed" o "Unauthorized"

Compruebe su panel de FreeClaude para confirmar que su temporizador de acceso está activo. Si su temporizador ha expirado, invite a otro amigo para extenderlo. Si el temporizador está activo pero la autenticación sigue fallando, intente ejecutar claude logout seguido de claude login para volver a autenticarse.

Respuestas lentas o tiempos de espera agotados

Claude Code requiere una conexión a Internet estable para comunicarse con los servidores de Anthropic. Compruebe la calidad de su conexión. Si está en WiFi, pruebe con una conexión por cable para las sesiones de Claude Code extendidas para evitar conexiones interrumpidas a mitad de operación.

Errores de permisos al instalar en Mac/Linux

Evite usar sudo npm install -g ya que puede causar problemas de permisos. En su lugar, configure npm para usar un directorio con permisos de escritura para el usuario:

mkdir ~/.npm-global
npm config set prefix ~/.npm-global
Luego añada export PATH=~/.npm-global/bin:$PATH a su perfil de shell.

Claude Code realiza un cambio que no quería

Claude Code realiza commits de git de forma incremental. Ejecute git log para ver los commits recientes y git revert HEAD para deshacer el commit más reciente. Para sesiones más largas, Claude Code crea commits en puntos de control lógicos, lo que facilita volver a cualquier estado anterior.

Preguntas Frecuentes

¿Funciona Claude Code sin conexión?

No. Claude Code envía el contexto de su código a los servidores de Anthropic para el procesamiento de IA. Se requiere una conexión a Internet estable durante todas las sesiones.

¿Mi código se envía a Anthropic cuando uso Claude Code?

Sí. El contenido de los archivos que Claude Code lee se envía a la API de Anthropic para su procesamiento. Se aplica la política de privacidad de Anthropic. No use Claude Code en archivos que contengan secretos, credenciales o información propietaria muy sensible sin revisar las políticas de manejo de datos de Anthropic para su caso de uso.

¿Puedo usar Claude Code en un contenedor Docker?

Sí, con imágenes Docker estándar de Node.js. Instale claude-code a través de npm en el contenedor y monte el directorio de su proyecto como un volumen.

¿Qué versión de Node.js requiere Claude Code?

Se requiere Node.js 18.0 o superior. Se recomienda Node.js 20 LTS o Node.js 22 LTS para la mejor experiencia.

¿Cómo actualizo Claude Code?

Ejecute npm update -g @anthropic-ai/claude-code para actualizar a la última versión. También puede ejecutar npm install -g @anthropic-ai/claude-code@latest para forzar la instalación de una versión específica.

¿Puedo usar Claude Code en pipelines de CI/CD?

Claude Code está diseñado para el uso interactivo de desarrolladores. Para casos de uso automatizados de CI/CD, la API de Anthropic es más apropiada. Sin embargo, algunos equipos crean scripts de sesiones no interactivas de Claude Code para tareas de revisión específicas en pipelines de CI.

¿Necesita Ayuda?

Si encuentra problemas de instalación o uso no cubiertos aquí, contacte a nuestro equipo de soporte a través del bot de Telegram de FreeClaude. También puede visitar nuestra comparación de asistentes de programación de IA para entender por qué Claude Code lidera el campo, o nuestra guía de inicio si necesita ayuda para activar su cuenta de FreeClaude primero.

Configuración Avanzada para Flujos de Trabajo Profesionales

Una vez que Claude Code esté instalado y funcionando, estas opciones de configuración mejoran significativamente la experiencia para los flujos de trabajo de desarrollo profesional:

Crear un CLAUDE.md Global

Además de los archivos CLAUDE.md a nivel de proyecto, puede crear una configuración global de Claude Code en ~/.claude/CLAUDE.md. Este archivo se carga para cada sesión de Claude Code independientemente del proyecto y es ideal para preferencias personales que se aplican universalmente:

• Su estilo preferido de comentarios de código
• Preferencias predeterminadas de lenguaje de programación
• Convenciones personales para el formato de mensajes de commit
• Recordatorio sobre las herramientas que siempre desea que Claude use (como ejecutar pruebas antes de confirmar)
• Cualquier contexto personal sobre la configuración de su entorno de desarrollo

Configurar la Selección de Modelo

Claude Code puede configurarse para usar un modelo específico de forma predeterminada mediante el indicador --model o configurándolo en la configuración:

• claude --model claude-opus-4-7 — Usar Opus para máxima capacidad
• claude --model claude-sonnet-4-6 — Usar Sonnet para respuestas más rápidas (recomendado para la mayoría de sesiones)
• claude --model claude-haiku-4-5 — Usar Haiku para tareas ligeras y rápidas

También puede cambiar de modelo a mitad de sesión con el comando /model sin perder el contexto de la conversación.

Alias de Shell para un Inicio Más Rápido

Añada estos alias a su perfil de shell (~/.zshrc o ~/.bashrc) para una invocación más rápida de Claude Code:

• alias cc="claude" — Lanzamiento rápido
• alias cc-fast="claude --model claude-sonnet-4-6" — Modo rápido con Sonnet
• alias cc-deep="claude --model claude-opus-4-7" — Análisis profundo con Opus
• alias cc-review="claude --print /review" — Revisión de código no interactiva

Integración con el Flujo de Trabajo de Git

Claude Code se integra profundamente con los flujos de trabajo de git. Estos son los patrones en los que confían los usuarios experimentados:

Flujo de Trabajo de Rama de Función

Siempre inicie una sesión de Claude Code para trabajo significativo creando una nueva rama:

1. Crear rama: git checkout -b feature/mi-funcion
2. Iniciar Claude Code: claude
3. Describir la función y dejar que Claude Code la implemente
4. Revisar el diff: git diff main
5. Fusionar cuando esté satisfecho: git checkout main && git merge feature/mi-funcion

Este flujo de trabajo le da control completo sobre lo que se fusiona con su rama principal, al tiempo que permite que Claude Code trabaje libremente en el entorno de la rama de función.

Usar Claude Code para Revisión de Código

Ejecute claude en cualquier rama y use el comando /review para obtener una revisión completa de todos los cambios no confirmados. Esto es particularmente valioso como verificación previa al commit para detectar problemas antes de que se envíen a su repositorio.

Asistencia de Rebase Interactivo

Pida a Claude Code que le ayude a limpiar historiales de commits desordenados: "Tengo 12 commits en esta rama de exploración y errores. Por favor, condénsalos en 3 commits lógicos con mensajes claros que describan lo que logra cada grupo de cambios." Claude Code analiza los commits y proporciona los comandos git rebase necesarios para reestructurarlos limpiamente.

Usar Claude Code Junto a su IDE

Claude Code y su IDE no son mutuamente excluyentes: son herramientas complementarias que funcionan mejor en combinación:

• IDE para: Programación activa, resaltado de sintaxis, autocompletado, depuración con puntos de interrupción, exploración visual de archivos y operaciones git basadas en IU
• Claude Code para: Refactorización de múltiples archivos, implementación de funciones a partir de descripciones en lenguaje natural, corrección autónoma de errores, generación de pruebas, documentación y comprensión de partes desconocidas de grandes bases de código

Un flujo de trabajo común: use su IDE para el desarrollo activo de funciones, cambie a Claude Code cuando se encuentre con un problema complejo o necesite realizar cambios coordinados en múltiples archivos, luego vuelva a su IDE para revisar y continuar desarrollando sobre la implementación de Claude. Las dos herramientas nunca entran en conflicto porque Claude Code opera en su sistema de archivos real: los cambios realizados en Claude Code aparecen inmediatamente en el editor de su IDE.

Configuración Óptima del Espacio de Trabajo para Sesiones de Claude Code

Los desarrolladores profesionales que usan Claude Code de forma intensiva han convergido en configuraciones de espacio de trabajo que maximizan la productividad:

• Diseño de terminal dividido — Ejecute Claude Code en un panel de terminal, mantenga un segundo panel para ejecutar su aplicación, pruebas o monitorear registros. Vea cómo aparecen los resultados de las pruebas mientras Claude Code corrige errores en tiempo real.
• Git diff en IDE junto al terminal — Mantenga su IDE abierto a la vista de diferencias de control de código fuente. A medida que Claude Code modifica archivos, ve los cambios resaltados en tiempo real en su IDE sin interrumpir la sesión de Claude Code.
• Persistencia de sesión de Tmux o iTerm2 — Use un multiplexor de terminal para mantener activas las sesiones de Claude Code durante interrupciones de red y cierres de la tapa del portátil. Esto es especialmente importante para las sesiones autónomas largas (más de 30 minutos) donde las caídas de conexión de otro modo perderían el progreso.
• Directorios de proyecto dedicados — Mantenga sus proyectos bien organizados con nombres de directorio claros. Claude Code lee la estructura de su directorio como parte de su comprensión del proyecto, y una organización limpia le ayuda a comprender inmediatamente los límites del proyecto.