Claude Code se instala con un único comando en todas las plataformas compatibles, y toda la primera ejecución consiste en: instalar, escribir claude, iniciar sesión. Esta guía incluye el comando exacto para cada sistema operativo, qué comprobar cuando no funcione y cómo apuntarlo a otro endpoint una vez que funcione.
Comandos verificados 3 de octubre de 2026 con la documentación de configuración de Claude Code de Anthropic.
Antes de empezar
| Requisito | Compatibilidad |
|---|---|
| Sistema operativo | macOS 13.0+, Windows 10 1809+ / Server 2019+, Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+ |
| Hardware | 4 GB+ de RAM, x64 o ARM64 |
| Shell | Bash, Zsh, PowerShell o CMD |
| Red | Se requiere conexión a Internet |
| Cuenta | Pro, Max, Team, Enterprise o Console; el plan gratuito de Claude.ai no incluye Claude Code |
Instalación: el instalador nativo
Este es el método recomendado en todas las plataformas. Instala un binario autónomo y se actualiza automáticamente en segundo plano.
# macOS, Linux, WSL
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.cmdSi no estás seguro de qué shell de Windows estás usando, el prompt te lo indica: PowerShell muestra PS C:\ y CMD muestra C:\ sin PS. Ejecutar el comando equivocado es el fallo de instalación más común en Windows; consulta la tabla de solución de problemas para ver el error exacto de cada caso.
Gestores de paquetes
Úsalos si prefieres que tu gestor de paquetes existente se encargue de la instalación. La contrapartida son las actualizaciones: ninguno de estos se actualiza automáticamente de forma predeterminada, a diferencia del instalador nativo.
# Homebrew (macOS, Linux) — stable channel
brew install --cask claude-code
# WinGet (Windows)
winget install Anthropic.ClaudeCode
# npm — requires Node.js 22+; never with sudo
npm install -g @anthropic-ai/claude-codeHomebrew publica dos casks: claude-code sigue el canal estable (normalmente con aproximadamente una semana de retraso y omitiendo versiones con regresiones importantes) y claude-code@latest distribuye cada versión de inmediato. Existen repositorios apt, dnf y apk firmados para Debian / Ubuntu, Fedora / RHEL y Alpine, cada uno con los mismos canales estable y latest.
En npm, no uses nunca sudo npm install -g: provoca problemas de permisos y supone un riesgo de seguridad. El paquete npm instala exactamente el mismo binario nativo que el instalador independiente, por lo que tampoco hay una dependencia de Node en tiempo de ejecución.
Verificar la instalación
claude --version # prints e.g. "2.1.211 (Claude Code)"
claude doctor # read-only install + settings diagnostics
claude # start a session in the current projectclaude doctor es el comando que debes recordar: muestra el estado de la instalación, los errores de validación de los archivos de configuración y las correcciones sugeridas sin iniciar una sesión, lo que lo convierte en la forma más rápida de distinguir una instalación dañada de una configuración dañada.
Primera ejecución e inicio de sesión
Abre un terminal en el proyecto en el que quieras trabajar y ejecuta claude. Se abrirá una sesión interactiva y te guiará durante el inicio de sesión en el navegador. Claude Code requiere una cuenta Pro, Max, Team, Enterprise o Console.
Hay un comportamiento que conviene conocer antes de que te sorprenda: si ANTHROPIC_API_KEY ya está definido en tu entorno, Claude Code te pide una vez que apruebes esa clave en lugar de abrir un navegador. Rechaza esa solicitud y la clave se ignorará silenciosamente a partir de entonces, sin nuevas solicitudes; parecerá exactamente que la variable no se está leyendo. Vuelve a activarla en /config → Usar clave de API personalizada.
Windows: nativo o WSL
| Opción | Requiere | Aislamiento | Elígela cuando |
|---|---|---|---|
| Windows nativo | Nada; Git for Windows es opcional | No compatible | Tus proyectos y herramientas son nativos de Windows |
| WSL 2 | WSL 2 habilitado | Compatible | Cadenas de herramientas de Linux o ejecución de comandos en un entorno aislado |
| WSL 1 | WSL 1 habilitado | No compatible | WSL 2 no está disponible |
En Windows nativo, instalar Git for Windows es opcional, pero se recomienda: proporciona Git Bash, que respalda la herramienta Bash. Sin él, Claude Code ejecuta los comandos de shell mediante la herramienta PowerShell. En WSL, instala e inicia claude dentro del terminal de WSL, no desde PowerShell.
Solución de problemas
| Síntoma | Causa y solución |
|---|---|
The token '&&' is not a valid statement separator | Has ejecutado el comando de CMD en PowerShell. Usa la línea irm … | iex en su lugar. |
'irm' is not recognized… | Lo contrario: has ejecutado el comando de PowerShell en CMD. Usa la línea curl … install.cmd. |
syntax error near unexpected token '<', un 403 u otro error de curl | La descarga no devolvió el script; normalmente se debe a un proxy o a un filtro de red entre tú y el instalador. Reintenta o usa en su lugar una instalación mediante un gestor de paquetes. |
claude: command not found después de una instalación limpia | Abre un terminal nuevo para que el shell detecte el directorio de instalación y, después, ejecuta claude doctor. Otra instalación más antigua o un alias de shell obsoleto es la otra causa habitual. |
| Errores de permisos durante una instalación de npm | Has usado sudo o el directorio global de npm no permite escritura. Corrige la propiedad del directorio en lugar de volver a ejecutarlo con sudo; un directorio global sin permisos de escritura también impide las actualizaciones automáticas. |
Falta el binario nativo después de npm install -g | Tu gestor de paquetes está configurado para omitir dependencias opcionales. El binario de la plataforma se distribuye como una de ellas, así que permítelas y vuelve a instalar. |
| La instalación falla en Alpine u otra distribución musl | Alpine se distribuye sin bash y curl. Instala bash curl libgcc libstdc++ ripgrep y establece USE_BUILTIN_RIPGREP en "0" dentro del bloque env de tu archivo de configuración. |
| Fallan la búsqueda y el descubrimiento de archivos | Normalmente ripgrep viene incluido. Si no puede ejecutarse en tu plataforma, instala el ripgrep del sistema y establece USE_BUILTIN_RIPGREP=0. |
| Falta la herramienta Bash en Windows nativo | Instala Git for Windows. Si Claude Code todavía no encuentra Git Bash, establece CLAUDE_CODE_GIT_BASH_PATH en el bloque env de ~/.claude/settings.json. |
401 una vez configurada una clave | La clave está en el encabezado que el servidor no lee: alterna entre ANTHROPIC_AUTH_TOKEN y ANTHROPIC_API_KEY. Encontrarás los detalles en la guía de claves de API. |
Apuntar Claude Code a Kunavo
Una vez que funcione, Claude Code operará con cualquier endpoint que sirva la API Anthropic Messages: lee ANTHROPIC_BASE_URL de forma nativa, por lo que se trata de una configuración compatible y no de una solución alternativa. Sin plugin, sin proxy y sin binario modificado:
export ANTHROPIC_BASE_URL=https://api.kunavo.com
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-5Cinco cosas sobre ese bloque, cada una de las cuales puede costarte una hora si la configuras mal:
ANTHROPIC_BASE_URLes solo el origen. Claude Code añade/v1/messagespor sí mismo; incluir la ruta provoca un 404.- Usa
ANTHROPIC_AUTH_TOKEN, noANTHROPIC_API_KEY. Van en encabezados HTTP diferentes. El token bearer tiene efecto inmediato, mientras queANTHROPIC_API_KEYrequiere la aprobación única descrita arriba. Kunavo lee la clave de cualquiera de los dos encabezados, incluido/v1/models, por lo que en Kunavo ese paso de aprobación es lo que los diferencia. - Establece
ANTHROPIC_MODELexplícitamente. Kunavo compara los identificadores de modelo exactamente y no crea alias para nombres con fecha, por lo queclaude-sonnet-4-5-20250929devuelve 404 mientrasclaude-sonnet-5funciona. - Fija también
ANTHROPIC_DEFAULT_OPUS_MODELyANTHROPIC_DEFAULT_SONNET_MODEL. El valor predeterminado integrado de Claude Code y su aliasopusresuelven ambos al Opus más reciente y, si Kunavo aún no ofrece ese modelo, la primera solicitud devuelve 404. El bloque fijaopusen Opus 5.5 (claude-opus-5-5), que requiere Claude Code v2.1.280 o posterior; ejecutaclaude updateen una instalación anterior. El aliassonnetsolicita Sonnet 5.5, que Kunavo no ofrece, por lo que, sin la fijación de sonnet/model sonnet, la fase de ejecución deopusplany cualquier subagente configurado conmodel: sonnetdevuelven un 404. ANTHROPIC_DEFAULT_HAIKU_MODELcubre las llamadas en segundo plano que Claude Code realiza por su cuenta para resúmenes y títulos.claude-haiku-4-5cuesta $0.70 / $3.50 por 1M frente a $1.40 / $7.00 para el modelo principal, por lo que es una sola línea para obtener un ahorro permanente.
Coloca estos valores en el bloque env de ~/.claude/settings.json en lugar de exportarlos en el shell si quieres que los editores y agentes en segundo plano también los vean, y nunca en el .claude/settings.json confirmado de un proyecto. Crea la clave sk-kn- en el panel después de registrarte; una recarga de $10 es el mínimo, no hay cuota mensual y el saldo no caduca. El coste por token de cada modelo, comparado con los precios oficiales de la API de Anthropic, determina hasta dónde llega ese $10.
Qué cambia detrás de una puerta de enlace
La programación, las herramientas, los subagentes, MCP, los hooks y la caché de prompts no se ven afectados. Sí cambian tres cosas, y conviene conocerlas antes de pensar que algo está roto:
- Remote Control y el dictado por voz no están disponibles. Ambos necesitan una identidad de claude.ai, que una credencial de puerta de enlace sustituye.
/fastpuede indicar que el modo rápido está desactivado. La comprobación de disponibilidad llama directamente a Anthropic en lugar de seguir tu URL base. Las solicitudes normales no se ven afectadas.- Los recuentos de
/contextpasan a ser estimaciones locales. El recuento de tokens es el único endpoint que la especificación de la puerta de enlace de Anthropic marca como opcional, y Claude Code calcula una estimación local cuando está ausente; Kunavo no sirve/v1/messages/count_tokensactualmente. La compactación automática y la sesión no se ven afectadas.
La lista completa, además de la decisión entre usar o no un enrutador, se encuentra en la guía del enrutador de Claude Code.
Preguntas frecuentes
¿Cómo instalo Claude Code?
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, o `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` en CMD. El instalador nativo es el método recomendado y se actualiza automáticamente en segundo plano. También son compatibles Homebrew (`brew install --cask claude-code`), WinGet (`winget install Anthropic.ClaudeCode`), npm y los repositorios apt/dnf/apk firmados, pero ninguno de ellos se actualiza automáticamente de forma predeterminada.
¿Necesito Node.js para instalar Claude Code?
No para el instalador nativo, Homebrew, WinGet o los repositorios de paquetes de Linux: todos instalan un binario nativo que no usa Node en tiempo de ejecución. Solo la ruta de instalación mediante npm implica Node y, a partir de v2.1.198, ese paquete requiere Node.js 22 o posterior. Incluso entonces, npm simplemente incorpora el mismo binario nativo mediante una dependencia opcional específica de cada plataforma.
¿Cuáles son los requisitos del sistema para Claude Code?
macOS 13.0+, Windows 10 1809+ o Windows Server 2019+, Ubuntu 20.04+, Debian 10+ o Alpine Linux 3.19+; 4 GB o más de RAM en un procesador x64 o ARM64; conexión a Internet; y Bash, Zsh, PowerShell o CMD como shell. También debes encontrarte en un país compatible con Anthropic.
¿Cómo inicio sesión en Claude Code por primera vez?
Ejecuta `claude` en un directorio de proyecto y sigue las indicaciones del navegador. Claude Code requiere una cuenta Pro, Max, Team, Enterprise o Console; el plan gratuito de Claude.ai no incluye acceso a Claude Code. Si la variable de entorno ANTHROPIC_API_KEY está definida, Claude Code te pide una vez que apruebes esa clave en lugar de abrir un navegador.
¿Puedo instalar Claude Code en Windows sin WSL?
Sí. Ejecuta el instalador de PowerShell o CMD e inicia `claude` desde cualquier terminal; no necesitas derechos de administrador. Git for Windows es opcional, pero se recomienda porque proporciona Git Bash, que respalda la herramienta Bash; sin él, Claude Code ejecuta los comandos de shell mediante la herramienta PowerShell. WSL 2 es la opción que debes elegir si quieres cadenas de herramientas de Linux o ejecución de comandos en un entorno aislado, algo que Windows nativo no admite.
¿Por qué `claude` muestra «command not found» después de la instalación?
El directorio de instalación no está en tu PATH dentro del shell que estás usando. Abre primero un terminal nuevo: el instalador añade ~/.local/bin en macOS y Linux, y una sesión existente no lo detectará. Ejecuta `claude doctor` para obtener diagnósticos de solo lectura de la instalación y los archivos de configuración. Otra instalación más antigua o un alias de shell sobrante es la otra causa habitual.
¿Cómo apunto Claude Code a un endpoint de API diferente?
Establece ANTHROPIC_BASE_URL en el origen de cualquier endpoint que proporcione la API de mensajes de Anthropic: Claude Code lo lee de forma nativa y añade /v1/messages por sí mismo, por lo que no intervienen ningún plugin ni proxy. Combínalo con ANTHROPIC_AUTH_TOKEN para la credencial y con un ANTHROPIC_MODEL explícito, y fija ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL y ANTHROPIC_DEFAULT_HAIKU_MODEL en modelos que ofrezca el endpoint, porque, de lo contrario, los alias opus y sonnet siguen los modelos más recientes de Anthropic. En Kunavo, esto ejecuta los mismos modelos Claude por 30% menos que el precio de lista de Anthropic, mediante pago por uso.
Siguientes pasos
- Clave de API de Claude Code: dónde obtenerla, dónde colocarla y la discrepancia de encabezados detrás de la mayoría de los errores 401.
- Precios de Claude Code: suscripción frente a API, tarifas por modelo y cuánto cuesta un mes.
- ¿Claude Code es gratis?: qué es gratis, qué no lo es y dónde se sitúa el límite.
- Ejecutarlo sin solicitudes de permiso: qué elimina realmente
--dangerously-skip-permissionsy tres medidas de contención que tardan aproximadamente un minuto cada una. - Claude Code frente a Codex CLI: si todavía estás eligiendo un agente de terminal.