Instalar Claude Code: el comando para Windows, macOS y Linux y cómo usarlo sin suscripción

Para instalar Claude Code basta con un comando: en macOS, Linux o WSL, ejecuta curl -fsSL https://claude.ai/install.sh | bash; en Windows, ejecuta irm https://claude.ai/install.ps1 | iex en PowerShell (en el símbolo del sistema, CMD, usa la línea de install.cmd más abajo). Después, abre un terminal nuevo, comprueba con claude --version y ejecuta claude para empezar. En la primera conexión hay dos opciones: 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 ninguna suscripción.

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

Antes de instalar

Instalar en macOS y Linux

Abre 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 automáticamente en segundo plano. El acceso directo queda en ~/.local/bin/claude, y un terminal que ya estuviera abierto no detecta el nuevo PATH; por eso, abre otra ventana antes de probar. En WSL el comando es el mismo.

Instalar en Windows

En Windows hay dos líneas diferentes, y la única diferencia es el terminal en el que estás. Si el prompt comienza con PS C:\Users\SeuNome>, es PowerShell; sin el PS, solo C:\Users\SeuNome>, es el símbolo del sistema (CMD). No es necesario ejecutarlo como administrador.

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

:: Windows Prompt de Comando (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

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

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

En WSL, ejecuta la línea de macOS/Linux dentro del terminal de WSL y abre claude allí mismo, no desde PowerShell ni desde CMD.

Mediante el gestor de paquetes

Funciona, con una diferencia importante: ninguno se actualiza automáticamente de forma predeterminada. Debes actualizarlos manualmente (brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). También hay 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 — exige Node.js 22 ou mais novo; nunca com 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 una advertencia EBADENGINE y la instalación termina. El paquete instala el mismo binario nativo, que no usa Node.js para ejecutarse. Nunca uses sudo npm install -g: causa problemas de permisos y supone un riesgo de seguridad.

Comprobar la instalación

claude --version   # imprime a versão, por exemplo 2.1.211 (Claude Code)
claude doctor      # diagnóstico da instalação e das configurações, sem abrir sessão

Guarda el claude doctor: sin iniciar sesión, muestra el estado de la instalación, los errores en los archivos de configuración y la solución sugerida; es la forma más rápida de saber si el problema está en la instalación o en la configuración.

Si aparece command not found: claude (o, en Windows, que no se reconoce claude), la carpeta de instalación no está en el PATH. En macOS y Linux, abre un terminal nuevo; si no se soluciona, añade ~/.local/bin al PATH en ~/.zshrc o en ~/.bashrc. En Windows, la carpeta es %USERPROFILE%\.local\bin; compruébalo y añádelo mediante PowerShell:

# 1. Veja se a pasta de instalação já está no PATH
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. Sem saída? Adicione ao PATH do usuário e abra um terminal novo
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. No terminal novo: se houver duas instalações, aparecem dois caminhos
where.exe claude

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

Ruta A — iniciar sesión con la suscripción

En la carpeta del proyecto, ejecute claude y siga el inicio de sesión en el navegador con una cuenta Pro, Max, Team, Enterprise o Console. Un detalle que suele confundir: si la variable ANTHROPIC_API_KEY ya está definida, Claude Code pregunta una vez si debe usar esa clave. Si la rechaza, la ignora en silencio y no vuelve a preguntar; parece que la variable no se está leyendo. Para reactivarla, vaya a /config → Use custom API key.

Ruta 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 Anthropic Messages API es una configuración compatible: sin plugin, sin proxy y sin binario modificado. El proceso: cree la cuenta, recargue el saldo (mínimo de $10), genere una clave sk-kn- en el panel de claves (solo aparece una vez) y defina las variables. En macOS y Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # só o domínio, sem /v1
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

En Windows, para probarlo en una ventana de PowerShell:

# Vale só para esta janela do PowerShell
$env:ANTHROPIC_BASE_URL = "https://api.kunavo.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-kn-..."
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
claude

Para dejarlo fijo, el mejor lugar es el bloque env del archivo de configuración del usuario, ~/.claude/settings.json (en Windows, %USERPROFILE%\.claude\settings.json). Allí las variables se aplican a cualquier terminal, a la extensión del editor y a los procesos en segundo plano. Si el archivo ya contiene otras configuraciones, solo añada el bloque env:

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

Cada una de estas líneas tiene una particularidad:

• ANTHROPIC_BASE_URL solo recibe el dominio. Claude Code añade /v1/messages; con /v1 al final, la solicitud se envía a /v1/v1/messages y devuelve 404.
• Use ANTHROPIC_AUTH_TOKEN, no ANTHROPIC_API_KEY. Se envían en encabezados HTTP diferentes: la primera envía Authorization: Bearer y funciona de inmediato; la segunda envía x-api-key y además requiere la aprobación única descrita arriba.
• Escriba el nombre exacto del modelo en ANTHROPIC_MODEL. Kunavo solo reconoce el nombre idéntico y no traduce los nombres antiguos con fecha en el sufijo.
• Fija también ANTHROPIC_DEFAULT_OPUS_MODEL y ANTHROPIC_DEFAULT_SONNET_MODEL. El modelo predeterminado de Claude Code y el alias opus apuntan al Opus más reciente y, si Kunavo aún no lo ofrece, la primera solicitud devuelve 404. El alias sonnet ya solicita Sonnet 5.5, que Kunavo no ofrece: sin fijarlo, /model sonnet, la fase de ejecución de opusplan y los subagentes con model: sonnet reciben 404. El alias opus queda fijado en Opus 5.5 (claude-opus-5-5), que requiere Claude Code v2.1.280 o posterior; en una instalación antigua, ejecuta claude update.
• ANTHROPIC_DEFAULT_HAIKU_MODEL cubre las llamadas en segundo plano que Claude Code realiza por sí solo (resúmenes, títulos). Apuntarlo a Haiku permite ahorrar sin esfuerzo.

Nunca coloque la clave en el .claude/settings.json del proyecto: ese archivo se sube a git y queda disponible para quien clone el repositorio. En la extensión de VS Code, las variables se configuran en claudeCode.environmentVariables, en la configuración de usuario del propio VS Code, porque la extensión verifica la credencial antes de iniciarse.

Tarifas por 1M de tokens, tomadas del catálogo:

Para cambiar de modelo dentro de la sesión, use /model con el nombre completo (por ejemplo /model claude-opus-5-5) o inicie Claude Code con claude --model claude-opus-5-5. El coste mensual y cuándo compensa más la suscripción se explican en la guía de precios de Claude Code.

Cómo saber qué ruta está activa

Dentro de Claude Code, ejecute /status. Una línea Auth token significa que la clave está activa; una línea Login method con una cuenta de claude.ai significa que la variable no se leyó. No se acumulan: con la variable definida, la suscripción queda inactiva; elimine la variable y volverá a la suscripción, sin reinstalar nada.

Detrás de una pasarela, cambian tres cosas: Remote Control y el dictado por voz no funcionan (requieren la identidad de claude.ai); /fast puede indicar que el modo rápido no está disponible, porque esa comprobación va directamente a Anthropic, pero las solicitudes normales no cambian; y las cifras de /context se convierten en estimaciones locales. El código, las herramientas, los subagentes, MCP, los hooks y el almacenamiento en caché de prompts funcionan igual. Los detalles están en la documentación de la integración (en inglés).

Pagar desde Brasil: Pix en el checkout

La suscripción de claude.ai es un cargo recurrente en dólares que requiere una tarjeta internacional habilitada para compras en el extranjero. En la ruta de la clave de API, la recarga pasa por el checkout de Stripe y Pix aparece como método de pago para quienes pagan desde Brasil: el precio está en USD y Stripe muestra el importe convertido a reales antes de que confirmes. En el checkout también aparecen las tarjetas internacionales (Visa, Mastercard, American Express), Apple Pay, Google Pay y Link. La billetera es prepaga —recarga mínima de $10, saldo que no caduca y las solicitudes fallidas no se cobran— y cada clave puede tener un límite mensual de gasto. El paso a paso, pantalla por pantalla, está en cómo pagar la API con Pix.

Errores comunes

Después de instalar

La primera vez, ejecute /init dentro del proyecto: Claude Code lee el repositorio y genera un CLAUDE.md con los comandos de prueba y las convenciones que encuentre. Revise el archivo y manténgalo breve: se carga en cada sesión. Entre tareas sin relación, /clear inicia una conversación nueva; cuando una tarea se alarga, /compact resume el historial y continúa.

Siendo sinceros sobre la elección: para quien usa Claude Code muchas horas al día, la cuota mensual de la suscripción suele resultar más barata; el pago por uso compensa cuando el uso fluctúa o cuando no quiere quedar limitado a la ventana de 5 horas, y un mes sin actividad cuesta cero. Con Kunavo utiliza capacidad compartida, sin cuota dedicada ni SLA contractual; quien necesite esas garantías debe contratar directamente con Anthropic.

Preguntas frecuentes