Guía de instalación de Claude Code — comandos para macOS y Windows; conexión posterior mediante suscripción o clave de API

La instalación de Claude Code solo requiere un comando: en macOS, Linux y WSL ejecuta curl -fsSL https://claude.ai/install.sh | bash; en Windows, ejecútalo en PowerShell con irm https://claude.ai/install.ps1 | iex (en el símbolo del sistema CMD, usa la línea install.cmd siguiente). Después de instalarlo, abre una terminal nueva, confirma con claude --version y ejecuta claude para empezar. Para 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 configurar las dos variables de entorno ANTHROPIC_BASE_URL y ANTHROPIC_AUTH_TOKEN para usar una clave de API con facturación por uso, sin necesidad de suscripción.

Comandos verificados en 11 de septiembre de 2026, según la documentación oficial de instalación de Anthropic. Esta página solo cubre la instalación y la primera conexión; para el uso diario después de instalarlo, consulta el tutorial de Claude Code.

Comprobaciones previas a la instalación

Instalación en macOS

Abre «Terminal» y pega esta línea:

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

Esta es la forma de instalación nativa recomendada oficialmente: instala un ejecutable independiente que se actualiza automáticamente en segundo plano. La entrada del ejecutable está en ~/.local/bin/claude; las terminales que ya estaban abiertas no leerán el nuevo PATH, así que abre una ventana nueva después de instalarlo. Linux y WSL usan el mismo comando.

Instalación en Windows

Windows tiene dos comandos distintos; la diferencia depende del tipo de terminal que abras. Si el indicador es PS C:\Users\你的名字>, es PowerShell; si no aparece PS y solo aparece C:\Users\你的名字>, es el símbolo del sistema (CMD). No hace falta ejecutarlo como administrador.

# 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.cmd

Pegar el comando en el lugar equivocado es el fallo más común en Windows. Si ejecutas el comando de CMD en PowerShell, verás The token '&&' is not a valid statement separator; si ejecutas el de PowerShell en CMD, verás 'irm' is not recognized as an internal or external command. Si pegas el comando de macOS curl … | bash en PowerShell, aparecerá A parameter cannot be found that matches parameter name 'fsSL'. En los tres casos, basta con volver a usar la línea correspondiente.

Se recomienda instalar también Git for Windows: Claude Code usará el Git Bash incluido para ejecutar comandos; si no está instalado, usará PowerShell. Si está instalado pero no se encuentra Git Bash, añade CLAUDE_CODE_GIT_BASH_PATH a la sección env del archivo de configuración y apunta a la ruta de bash.exe.

Si eliges WSL, ejecuta la línea anterior de macOS／Linux dentro de una terminal de WSL e inicia también claude allí, no desde PowerShell o CMD.

Instalación mediante un gestor de paquetes

También puedes dejar que tu gestor de paquetes existente lo administre; el coste es que por defecto ninguno se actualizará automáticamente, así que tendrás que actualizarlo periódicamente (por ejemplo, brew upgrade claude-code, winget upgrade Anthropic.ClaudeCode). Debian／Ubuntu, Fedora／RHEL y Alpine también disponen de repositorios apt, dnf y apk oficiales firmados.

# Homebrew（macOS、Linux）— stable 通道
brew install --cask claude-code

# WinGet（Windows）
winget install Anthropic.ClaudeCode

# npm — 需要 Node.js 22 以上；絕對不要加 sudo
npm install -g @anthropic-ai/claude-code

La vía de npm requiere Node.js 22 o posterior desde v2.1.198; con una versión más antigua de Node.js, npm solo imprime una advertencia EBADENGINE, pero la instalación se completa. Instala el mismo ejecutable que el instalador nativo y no depende de Node.js durante la ejecución. No uses sudo npm install -g bajo ningún concepto: deja problemas de permisos y también supone un riesgo de seguridad.

Confirmar que la instalación se realizó correctamente

claude --version   # 正常會印出版本號，例如 2.1.211 (Claude Code)
claude doctor      # 唯讀的安裝與設定診斷，不會開啟工作階段

claude doctor es lo más importante que debes recordar: no inicia una sesión de trabajo; solo muestra el estado de la instalación, los errores del archivo de configuración y las soluciones recomendadas. Es la forma más rápida de distinguir entre una instalación defectuosa y una configuración defectuosa.

Si aparece command not found: claude, o 'claude' is not recognized en Windows, significa que el directorio de instalación no está en PATH. En macOS／Linux, abre primero una terminal nueva; si sigue sin funcionar, añade ~/.local/bin al PATH de ~/.zshrc o ~/.bashrc. La ubicación de instalación en Windows es %USERPROFILE%\.local\bin; compruébala y añádela con PowerShell:

# 1. 檢查安裝目錄是否已在 PATH 裡
$env:PATH -split ';' | Select-String '\.local\\bin'

# 2. 沒有任何輸出的話，把它加進「使用者」PATH，然後關掉終端機重開
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

# 3. 重開後再確認一次；若有兩份安裝，這行會列出兩個路徑
where.exe claude

Primera conexión: inicio de sesión con suscripción o clave con facturación por uso

Ruta A: iniciar sesión con una cuenta de suscripción

Ejecuta claude en la carpeta del proyecto y sigue las indicaciones del navegador para iniciar sesión con una cuenta Pro, Max, Team, Enterprise o Console. Ten en cuenta un detalle: si ANTHROPIC_API_KEY ya existe en el entorno, Claude Code te preguntará una vez si quieres usar esa clave; si eliges rechazarla, la ignorará silenciosamente después y no volverá a preguntarlo, lo que puede parecer que la variable no se ha leído. Para volver a activarla, ve a /config y selecciona Use custom API key.

Ruta B: sin suscripción, mediante una clave con facturación por uso

Claude Code admite ANTHROPIC_BASE_URL de forma nativa, por lo que apuntar a cualquier endpoint que proporcione la API Anthropic Messages es una configuración oficialmente compatible; no necesitas plugins, proxies ni un ejecutable modificado. Los pasos son: registrar una cuenta, añadir saldo (mínimo $10), crear en la página de gestión de claves una clave que empiece por sk-kn- (solo se mostrará una vez) y configurar las variables siguientes. macOS／Linux:

export ANTHROPIC_BASE_URL=https://api.kunavo.com   # 只寫到網域，不要加 /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, si quieres probarlo primero en una ventana de PowerShell:

# 只對這個 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 usarlo a largo plazo, se recomienda escribirlo en la sección env del archivo de configuración del usuario ~/.claude/settings.json (en Windows, %USERPROFILE%\.claude\settings.json). Al escribirlo ahí, todas las terminales, extensiones del editor y procesos en segundo plano podrán leerlo; si el archivo ya contiene otros ajustes, combina env con ellos:

{
  "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"
  }
}

Estas seis líneas tienen cada una un punto en el que un error de configuración puede hacerte perder mucho tiempo:

• ANTHROPIC_BASE_URL solo debe contener el dominio. Claude Code añade /v1/messages automáticamente; si añades /v1, se convierte en /v1/v1/messages y devuelve 404.
• Usa ANTHROPIC_AUTH_TOKEN, no ANTHROPIC_API_KEY. Se envían en cabeceras HTTP distintas: la primera envía Authorization: Bearer y surte efecto de inmediato; la segunda envía x-api-key y requiere la confirmación única descrita anteriormente.
• ANTHROPIC_MODEL debe contener el nombre completo y correcto del modelo. Kunavo solo reconoce nombres que coincidan exactamente; no asigna automáticamente nombres antiguos con sufijos de fecha.
• ANTHROPIC_DEFAULT_OPUS_MODEL se encarga del alias opus. El modelo predeterminado de Claude Code y el alias opus apuntan al Opus más reciente; si Kunavo aún no lo ofrece, devolverán 404, por lo que esta línea y ANTHROPIC_MODEL deben fijarse. Aquí se fija el alias opus en Opus 5.5 (claude-opus-5-5); requiere Claude Code v2.1.280 o posterior. En versiones anteriores, ejecuta claude update.
• ANTHROPIC_DEFAULT_SONNET_MODEL se encarga del alias sonnet. En la API de Anthropic, el alias sonnet apunta a Sonnet 5.5, modelo que Kunavo no ofrece. Sin esta fijación, el tiempo de ejecución de /model sonnet y opusplan, así como los subagentes configurados como model: sonnet, devolverán 404. Por eso aquí también se fija en Claude Sonnet 5 (claude-sonnet-5).
• ANTHROPIC_DEFAULT_HAIKU_MODEL controla las llamadas en segundo plano. Los resúmenes y títulos que genera Claude Code utilizan este modelo: Claude Haiku 4.5 cuesta $0.70 / $3.50 por cada 1M de tokens; el modelo principal Claude Sonnet 5 cuesta $1.40 / $7.00 (al mismo precio que Anthropic).

No escribas la clave en .claude/settings.json dentro del proyecto: ese archivo se confirmará en commit y se compartirá con todas las personas que clonen el proyecto. Si usas una extensión de VS Code, coloca las variables en claudeCode.environmentVariables de la configuración de usuario de VS Code, porque la extensión comprueba las credenciales antes de iniciarse.

Confirmar qué ruta está conectada

Ejecuta /status después de entrar en Claude Code. Si ves la línea Auth token, la clave está activa; si ves Login method y aparece una cuenta de claude.ai, las variables no se han leído. No se combinan: mientras las variables de la clave estén presentes, la suscripción iniciada queda en pausa; elimina las variables para volver a la suscripción, sin reinstalar nada.

Al pasar por una pasarela, tres cosas son diferentes: Remote Control y la entrada de voz requieren una identidad de claude.ai y no estarán disponibles; la comprobación de disponibilidad de /fast consulta directamente a Anthropic y puede indicar que no está disponible, aunque las solicitudes normales no se vean afectadas; las cifras de /context pasan a ser estimaciones locales. La programación, las herramientas, los subagentes, MCP, los hooks y la caché de indicaciones siguen funcionando con normalidad. Consulta la explicación completa en la documentación de integración de Claude Code y la guía de claves de API de Claude Code (ambas en inglés).

Tabla de errores frecuentes

Después de instalarlo

La primera vez que entres en un proyecto, ejecuta /init para que lea todo el proyecto y genere CLAUDE.md. El tutorial de Claude Code explica cómo cambiar entre Opus, Sonnet y Haiku según la tarea, cuánto cuesta realmente una sesión y cómo reducir el coste con /clear y /compact.

También conviene decirlo con honestidad al elegir una ruta: para quienes interactúan durante muchas horas al día y tienen un uso elevado, la cuota mensual fija suele resultar más económica; la facturación por uso es adecuada cuando el uso fluctúa mucho o no quieres quedar limitado por una ventana de uso de 5 horas, y los meses sin actividad cuestan $0. Con Kunavo usas capacidad compartida, sin cuota dedicada ni SLA contractual; los equipos que necesiten esas garantías deberían contratar directamente a Anthropic. Las cuotas mensuales y el punto de equilibrio de ambas rutas aparecen en Coste de Claude Code.

Preguntas frecuentes