Cómo instalar Claude Code en tu terminal (paso a paso)

Claude Code es la herramienta de línea de comandos (CLI) oficial de Anthropic que ejecuta el modelo Claude directamente en tu terminal. A diferencia de un chat web, Claude Code lee tus archivos locales, edita código, ejecuta comandos del sistema y trabaja sobre repositorios reales sin copiar y pegar nada. Anthropic la lanzó en 2024 como parte de su apuesta por el agent coding.

El concepto central es la programación asistida por agente: en lugar de pedirle a la IA un fragmento de código que luego pegas, le pides una tarea —»añade tests a este módulo», «refactoriza esta función», «arregla este bug»— y la herramienta la ejecuta dentro de tu proyecto. Tú revisas el resultado, igual que con una pull request de un colega.

Diferencias con Claude.ai y la API

Las tres herramientas usan el mismo modelo pero resuelven cosas distintas. Esta tabla aclara cuándo usar cada una.

Antes de ejecutar nada en la terminal, comprueba estos cuatro requisitos. Saltarse uno provoca el 90% de los errores que aparecen más adelante.

Para gestionar versiones de Node sin volverte loco, instala nvm (Node Version Manager), un script que permite cambiar de versión por proyecto sin tocar la instalación del sistema, en Mac/Linux, o nvm-windows en Windows.

En macOS la instalación recomendada usa npm de forma global y tarda menos de un minuto si ya tienes Node.js instalado. Si no, instala Node primero con Homebrew.

Instalación con npm

# 1. Verificar Node.js
node --version
# debe devolver v18.0.0 o superior

# 2. Instalar Claude Code
npm install -g @anthropic-ai/claude-code

# 3. Verificar instalación
claude --version

Verificar que funciona

Si claude --version devuelve un número, la CLI está instalada correctamente. Aún no puede hablar con la API porque falta la API key —lo cubrimos en el apartado 6—. Si en su lugar ves «command not found», salta a la sección de errores.

En Linux el proceso es prácticamente idéntico a macOS, pero conviene evitar el Node.js de los repositorios oficiales de la distribución —suele estar desactualizado—. Lo recomendable es usar NodeSource o nvm.

# 1. Instalar Node.js v20 LTS desde NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 2. Instalar Claude Code
sudo npm install -g @anthropic-ai/claude-code

# 3. Verificar
claude --version

En Windows hay dos caminos: instalar Node.js nativo desde el instalador oficial, o usar WSL (Windows Subsystem for Linux), la capa de compatibilidad que permite ejecutar Linux dentro de Windows, y seguir el flujo de Linux. WSL es la opción recomendada porque Claude Code está pensado para entornos tipo UNIX y algunas funciones de shell se comportan mejor.

Opción A: WSL (recomendada)

Opción B: Node.js nativo en Windows

Para que Claude Code hable con el modelo necesita una API key, la clave de autenticación que identifica tu cuenta Anthropic en cada llamada. Sin ella, la CLI está instalada pero inútil. La configuración correcta es persistente: la guardas una vez y olvidate.

# Añadir al final de ~/.zshrc o ~/.bashrc
export ANTHROPIC_API_KEY="sk-ant-tu-clave-aqui"

# Recargar el shell
source ~/.zshrc

# Verificar que la variable está cargada
echo $ANTHROPIC_API_KEY

La forma correcta de empezar es dentro de un repositorio. Claude Code lee el contexto del proyecto (estructura, lenguajes, dependencias) y a partir de ahí entiende qué le pides. Lanzarlo en una carpeta vacía da resultados pobres.

Ejemplo real con un repositorio

# Entrar al proyecto
cd ~/proyectos/mi-app

# Arrancar Claude Code en modo interactivo
claude

# Ya dentro de la sesión, escribe en lenguaje natural:
# > explícame la estructura de este repositorio
# > añade un test unitario para utils/parser.js
# > arregla el bug del issue #42

Estos son los tres fallos que aparecen una y otra vez en foros de soporte. Si te topas con uno, salta directamente al apartado que corresponde.

«command not found» tras instalar

Significa que npm instaló el paquete pero el binario no está en tu PATH, la lista de rutas donde el shell busca comandos ejecutables. Ocurre sobre todo en Linux con npm configurado en home o en macOS con shells personalizados.

# Ver dónde npm instala los binarios globales
npm config get prefix

# Añadir esa ruta + /bin al PATH
export PATH="$(npm config get prefix)/bin:$PATH"

# Guardarlo en el shell
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc

API key no reconocida

Si claude arranca pero responde con «authentication error» o «invalid API key», revisa tres cosas en este orden: que la variable ANTHROPIC_API_KEY está exportada (echo $ANTHROPIC_API_KEY), que no tiene espacios ni comillas extra al copiarla, y que la key sigue activa en la consola de Anthropic. Las keys revocadas no avisan.

Versión de Node incompatible

El error suele ser explícito: «requires Node.js version 18 or higher». La solución más limpia es instalar nvm y cambiar de versión sin desinstalar nada del sistema.

# Instalar nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Recargar shell e instalar Node v20
source ~/.zshrc
nvm install 20
nvm use 20

# Reinstalar Claude Code en la nueva versión
npm install -g @anthropic-ai/claude-code

Claude Code es potente pero no es la herramienta correcta para todo. Estos cuatro casos justifican usar otra cosa:

¿Es gratis Claude Code?

La CLI en sí es gratuita y open source. Lo que se paga es el uso del modelo Claude a través de la API de Anthropic, facturado por tokens consumidos (entrada y salida). Una sesión típica de desarrollo de una hora cuesta entre 0,30 y 3 USD según el modelo y el tamaño del contexto enviado.

¿Cuánto se tarda en instalar Claude Code?

Menos de cinco minutos si ya tienes Node.js v18 o superior instalado. El comando npm install -g @anthropic-ai/claude-code descarga el paquete en 30-60 segundos. La configuración de la API key añade otros 2-3 minutos. Si necesitas instalar Node desde cero, suma 5-10 minutos extra.

¿Funciona Claude Code sin internet?

No. Cada interacción envía tu petición y el contexto relevante a los servidores de Anthropic y recibe la respuesta. Sin conexión, la CLI devuelve error de red y no realiza ninguna acción local.

¿Qué diferencia hay con Claude.ai?

Claude.ai es la interfaz web de chat para conversación, redacción y análisis. Claude Code es una herramienta de terminal específica para programar: lee tus archivos, ejecuta comandos y edita código directamente en tu máquina. Mismo modelo, contextos de uso distintos.

¿Anthropic entrena con mi código?

Por defecto, no. Los datos enviados vía API a través de Claude Code no se utilizan para entrenar modelos, según la política comercial de Anthropic. Para entornos con requisitos estrictos, los planes Enterprise ofrecen zero data retention (los datos no se almacenan después de la respuesta).