Cómo instalar Claude Code en Windows, macOS y Linux — y cómo usarlo sin suscripción

Para instalar Claude Code basta un comando: en macOS, Linux o WSL ejecuta curl -fsSL https://claude.ai/install.sh | bash; en Windows, irm https://claude.ai/install.ps1 | iex en PowerShell (en el Símbolo del sistema, CMD, usa la línea de install.cmd que verás más abajo). Después abre una terminal nueva, comprueba con claude --version, entra en la carpeta de tu proyecto y ejecuta claude; el primer comando útil es /init. Para conectarte tienes dos caminos: iniciar sesión con una cuenta Pro, Max, Team, Enterprise o Console (el plan gratuito de Claude.ai no incluye Claude Code) o definir dos variables de entorno, ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN, y usar una clave de API de pago por uso, sin suscripción.

Comandos comprobados el 11 de septiembre de 2026 con la documentación oficial de instalación de Anthropic.

Requisitos

Instalar en macOS y Linux

Abre la Terminal y pega:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

Es el método recomendado: instala un binario independiente que se actualiza solo en segundo plano. El ejecutable queda en ~/.local/bin/claude y una terminal que ya estaba abierta no ve el PATH nuevo, así que abre otra ventana antes de probar. En WSL el comando es el mismo.

Instalar Claude Code en Windows

En Windows hay dos líneas distintas y lo único que cambia es la terminal. Si el prompt empieza por PS C:\Users\TuNombre>, estás en PowerShell; sin el PS, solo C:\Users\TuNombre>, es el Símbolo del sistema (CMD). No hace falta ejecutarlo como administrador.

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows Símbolo del sistema (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Pegar la línea en la terminal equivocada es el fallo más habitual. La de CMD en PowerShell da The token '&&' is not a valid statement separator; la de PowerShell en CMD da 'irm' is not recognized as an internal or external command (en un Windows en español, «no se reconoce como un comando interno o externo»); y el curl … | bash de macOS pegado en PowerShell da A parameter cannot be found that matches parameter name 'fsSL'. En los tres casos basta con usar la línea que corresponde.

Instalar Git for Windows es opcional pero recomendable: Claude Code usa su Git Bash para ejecutar comandos y, sin él, usa PowerShell. Si Git está instalado y aun así no encuentra Git Bash, define CLAUDE_CODE_GIT_BASH_PATH en el bloque env de la configuración con la ruta de bash.exe.

Con WSL, ejecuta la línea de macOS/Linux dentro de la terminal de WSL y abre claude ahí, no desde PowerShell ni desde CMD.

Con un gestor de paquetes

También funciona, con una diferencia importante: ninguno se actualiza solo por defecto (tendrás que ejecutar brew upgrade claude-code o winget upgrade Anthropic.ClaudeCode). Existen además repositorios apt, dnf y apk firmados para Debian/Ubuntu, Fedora/RHEL y Alpine.

# Homebrew (macOS, Linux) — canal stable
brew install --cask claude-code

# WinGet (Windows)
winget install Anthropic.ClaudeCode

# npm — requiere Node.js 22 o posterior; nunca con sudo
npm install -g @anthropic-ai/claude-code

Con npm, desde la versión 2.1.198 el paquete requiere Node.js 22 o posterior; con un Node antiguo npm solo muestra un aviso EBADENGINE y la instalación termina. Instala el mismo binario nativo, que no usa Node.js para ejecutarse. Nunca uses sudo npm install -g: provoca problemas de permisos y es un riesgo de seguridad.

Comprobar la instalación

claude --version   # imprime la versión, por ejemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico de la instalación y la configuración, sin abrir sesión

Quédate con claude doctor: sin abrir sesión, muestra el estado de la instalación, los errores de los archivos de configuración y la solución sugerida. Es la forma más rápida de saber si falla la instalación o la configuración.

Si ves command not found: claude (o, en Windows, que claude no se reconoce), la carpeta de instalación no está en el PATH. En macOS y Linux abre una terminal nueva y, si sigue igual, añade ~/.local/bin al PATH en ~/.zshrc o ~/.bashrc. En Windows la carpeta es %USERPROFILE%\.local\bin; compruébala y añádela desde PowerShell:

# 1. Comprueba si la carpeta de instalación ya está en el PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. ¿Sin salida? Añádela al PATH de usuario y abre una terminal nueva
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. En la terminal nueva: si hay dos instalaciones, verás dos rutas
where.exe claude

Primera conexión: suscripción o clave de API

Opción A — iniciar sesión con tu suscripción

En la carpeta del proyecto ejecuta claude y sigue el inicio de sesión en el navegador con una cuenta Pro, Max, Team, Enterprise o Console. Un detalle que confunde: si la variable ANTHROPIC_API_KEY ya está definida, Claude Code te pregunta una sola vez si quieres usar esa clave. Si dices que no, la ignora a partir de entonces sin volver a preguntar, y parece que la variable no se lee. Para reactivarla: /config → Use custom API key.

Opción B — sin suscripción, con una clave de pago por uso

Claude Code lee ANTHROPIC_BASE_URL de forma nativa, así que apuntarlo a cualquier endpoint de la Anthropic Messages API es una configuración admitida: sin plugins, sin proxy y sin binarios modificados. Los pasos: crea la cuenta, recarga saldo (mínimo $10), genera una clave sk-kn- en el panel de claves (se muestra una sola vez) y añade este bloque env a tu configuración de usuario, ~/.claude/settings.json (en Windows, %USERPROFILE%\.claude\settings.json). Así lo ven todas las terminales, la extensión del editor y los procesos en segundo plano:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kunavo.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-kn-...",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

Para probar antes en una sola ventana de PowerShell:

# Solo para esta ventana de PowerShell (en macOS/Linux: export VARIABLE=valor)
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

• ANTHROPIC_BASE_URL lleva solo el dominio. Claude Code añade /v1/messages; con /v1 al final la petición va a /v1/v1/messages y devuelve 404.
• Usa ANTHROPIC_AUTH_TOKEN, no ANTHROPIC_API_KEY. Van en cabeceras HTTP distintas: la primera envía Authorization: Bearer y funciona al momento; la segunda envía x-api-key y además pasa por la aprobación única de arriba.
• Escribe el nombre exacto del modelo en ANTHROPIC_MODEL. Kunavo solo reconoce el nombre idéntico y no traduce nombres antiguos con fecha.
• ANTHROPIC_DEFAULT_HAIKU_MODEL cubre las llamadas de fondo que Claude Code hace por su cuenta (resúmenes, títulos): apuntarla a Haiku es ahorro sin esfuerzo.

No pongas nunca la clave en el .claude/settings.json del proyecto: ese archivo va al repositorio. En la extensión de VS Code, las variables van en claudeCode.environmentVariables, dentro de la configuración de usuario de VS Code, porque la extensión comprueba las credenciales antes de arrancar.

Tarifas por 1M de tokens, leídas del catálogo:

Cómo saber qué opción está activa

Dentro de Claude Code, ejecuta /status. Una línea Auth token significa que la clave está en uso; una línea Login method con una cuenta de claude.ai significa que la variable no se ha leído. No se suman: mientras la variable exista, la suscripción queda aparcada; quítala y Claude Code vuelve a la suscripción, sin reinstalar.

Detrás de un gateway cambian tres cosas: Remote Control y el dictado por voz no están disponibles (necesitan la identidad de claude.ai); /fast puede decir que el modo rápido no está disponible, porque esa comprobación va directa a Anthropic, aunque las peticiones normales no cambian; y las cifras de /context pasan a ser estimaciones locales. El código, las herramientas, los subagentes, MCP, los hooks y el prompt caching funcionan igual. Todos los detalles, en la documentación de la integración y en la guía de la API key de Claude Code (ambas en inglés).

Cómo usar Claude Code: los primeros pasos

# 1. Arranca siempre dentro de la carpeta del proyecto
cd ~/proyectos/mi-app
claude

# 2. Primer comando: lee el repositorio y genera CLAUDE.md
> /init

# 3. Pide las tareas en español y con la ruta del archivo
> cambia la validación de src/api/user.ts a zod y arregla los tests

# 4. Para tareas que tocan muchos archivos: Shift+Tab activa el modo plan

Claude Code te pide permiso antes de editar un archivo o ejecutar un comando; si va por mal camino, pulsa Esc para pararlo y /rewind para volver a un punto anterior. El CLAUDE.md que genera /init es un borrador: déjalo en lo que repetirías en cada sesión (comandos de test, convenciones, carpetas que no se tocan). Se carga en cada sesión y viaja en cada petición, y Anthropic recomienda no pasar de 200 líneas.

• Cambiar de modelo: /model seguido del nombre completo, por ejemplo /model claude-opus-5, o arranca con claude --model claude-opus-5. Hazlo entre tareas: cada modelo tiene su propia caché, y cambiar a mitad de tarea obliga a releer toda la conversación sin caché.
• /clear entre tareas sin relación. Empieza una conversación nueva y no cuesta nada; la anterior se recupera con /resume.
• /compact cuando una tarea se alarga: resume el historial y sigue. Con clave de API la caché dura cinco minutos por defecto, así que compacta antes de una pausa larga, no después.
• Lo que cuesta una sesión: /usage muestra los tokens, pero el importe que calcula es una estimación local a precio de lista de Anthropic; con Kunavo, el cargo real está en tu página de uso.

Pago y honestidad sobre la elección

El saldo es prepago mediante Stripe: tarjeta (Visa, Mastercard, American Express, JCB, UnionPay), Apple Pay o Link; la domiciliación SEPA no está disponible. La recarga mínima es de $10, el saldo no caduca, las peticiones fallidas no se cobran y cada clave admite un límite de gasto mensual. Todas las tarifas están en la página de precios.

Si usas Claude Code muchas horas al día, la cuota fija de una suscripción suele salir más barata; el pago por uso compensa cuando el uso es irregular o no quieres depender de la ventana de 5 horas, y un mes sin actividad cuesta cero. La comparación completa, en inglés, está en Claude Code pricing. A través de Kunavo usas capacidad compartida, sin cuota dedicada ni SLA contractual: si necesitas esas garantías, contrata directamente con Anthropic.

Preguntas frecuentes