Instalación y uso

📚 Navegación de la serie: El artículo anterior 01 · Introducción a Claude Code explicó claramente qué es y qué puede hacer. Este artículo te guiará para instalarlo realmente en tu computadora, iniciar sesión y ponerlo en marcha, además de explicar la actualización, desinstalación y resolución de problemas. El próximo artículo 03 · Cómo funciona Claude Code levantará la tapa para ver el ciclo del agente.

Te cuento una situación vergonzosa común. Muchas personas al instalar Claude Code por primera vez, buscan un tutorial antiguo y escriben de forma casual npm install -g @anthropic-ai/claude-code, y se quedan atascados con errores de permisos. Con prisa, simplemente usan sudo en él: se instala, pero las actualizaciones automáticas posteriores fallan todos los días, y claude doctor muestra todo en rojo. Se pasan casi una hora solucionando el problema antes de darse cuenta: El equipo oficial hace tiempo que enumeró el script nativo como la primera opción, y la ruta npm tiene más trampas. Lo que se podría hacer en 30 segundos con una línea de script curl, terminó por ser la ruta más tortuosa y propensa a errores.

Para ser francos, instalar Claude Code en sí no es difícil, lo difícil es que nadie te dice qué ruta tiene trampas. Este artículo marcará claramente el camino correcto para cada plataforma, para que no repitas los mismos errores.

Después de leer este artículo, obtendrás:

• Un comando para instalar Claude Code en Mac / Windows / Linux / WSL (con la salida esperada, para que puedas verificar si se instaló correctamente por tu cuenta)
• Una comparación de tres métodos de instalación (script oficial / administrador de paquetes / npm), para que sepas cuál elegir
• Operaciones completas de inicio de sesión, actualización y desinstalación
• Una tabla de referencia rápida de "Error → Cómo solucionarlo", que cubre el 90% de los obstáculos que encontrarán los principiantes

---

01 Antes de instalar, aclara tres cosas

No te apresures a escribir comandos. Demasiadas personas descubren a mitad de la instalación: "Oh, esta cuenta no se puede usar", un esfuerzo en vano. Confirma tres cosas primero.

La primera: ¿Tu computadora cumple los requisitos?

Claude Code no tiene altos requisitos de máquina, pero tiene algunas líneas estrictas (basadas en el sitio oficial):

Ítem	Requisitos
Sistema Operativo	macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+
Memoria	Más de 4 GB de RAM disponible
Procesador	x64 o ARM64
Red	Requiere conexión a Internet
Terminal	Bash, Zsh, PowerShell o CMD

Nota para versiones de macOS anteriores a la 13.0: Se puede instalar, pero colapsará tan pronto como lo ejecutes, reportando un error como dyld: cannot load: los sistemas antiguos no admiten las instrucciones utilizadas por el binario, no hay solución alternativa, solo puedes actualizar el sistema (en una máquina que todavía está en macOS 12, se negó obstinadamente a funcionar, todo estuvo bien al actualizar a la 14).

La segunda: Debes tener una cuenta válida

La regla más fácil de pasar por alto para los principiantes: la cuenta gratuita de Claude.ai no puede usar Claude Code.

El requisito oficial es ser una cuenta Pro, Max, Team, Enterprise o Console (API). Que chatees felizmente usando la versión web de Claude todos los días no significa que la cuenta pueda impulsar Claude Code; el nivel gratuito simplemente no funciona.

Si quieres usar modelos chinos (DeepSeek, GLM, Minimax) para ahorrar dinero, deja este paso de la cuenta por ahora, el artículo 05 hablará específicamente de conectar modelos de terceros. Este artículo asume que estás usando la cuenta oficial.

La tercera: ¿Desde dónde planeas usarlo?

Claude Code tiene tres formas de uso: CLI (Línea de comandos) tiene las funciones más completas y se ajusta más a la intención de diseño original; la App de escritorio no requiere tocar la terminal, se descarga y se usa; la Integración de editor (VS Code / JetBrains) se integra en el flujo de trabajo de desarrollo actual.

Mi sugerencia: aprende directamente el CLI. Este artículo también se centra en el CLI: es el más estable y universal. Una vez que lo aprendas, la App de escritorio y las extensiones del editor te tomarán solo unos minutos (se tratará en los artículos 08-10). Si realmente te resistes a la terminal, ve a https://claude.com/download para descargar la App de escritorio y úsala con clics.

💡 Resumen en una frase: Confirma tres cosas antes de comenzar la instalación: la versión del sistema es suficiente, la cuenta es de nivel de pago o Console, elige CLI para el uso, y una vez que pases estas tres etapas, escribe los comandos.

---

02 Instálalo: Un comando para cada plataforma

Primero la conclusión: Todas las plataformas deben dar prioridad al script de instalación oficial (oficialmente llamado "Instalación Nativa / Native Install", el más recomendado ahora). La mayor ventaja es: Después de la instalación, se actualiza automáticamente en segundo plano, por lo que básicamente no tienes que preocuparte más por las versiones.

Analogía: La instalación nativa es como instalar una App desde la tienda de aplicaciones. Haces clic en "Instalar" y se descarga sola, se instala sola y se actualiza sola en segundo plano en el futuro; el antiguo método de npm se parece más a "descargar un paquete de instalación y hacer clic manualmente en siguiente": se puede instalar, pero tienes que actualizarlo tú mismo y es propenso a problemas de permisos.

macOS / Linux / WSL

Abre la terminal y pega esta línea:

curl -fsSL https://claude.ai/install.sh | bash

Consejo para redes en China: claude.ai y el servidor de descarga downloads.claude.ai en la mayoría de los casos requieren magia de internet (VPN) para un acceso estable. Conéctate al proxy durante la instalación y evitarás más de la mitad de los errores de "atasco / tiempo de espera agotado".

Windows (Nativo, sin WSL)

Primero confirma en qué terminal estás: este es el punto de error más común para los usuarios de Windows, los comandos de PowerShell y CMD son diferentes:

PowerShell (El indicador se ve así PS C:\>):

irm https://claude.ai/install.ps1 | iex

CMD (El indicador es C:\>, sin el PS delante):

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

¿Cómo distinguirlos? Mira si el indicador comienza con PS: si lo tiene, es PowerShell; si no, es CMD. Si ejecutas ese comando de CMD con && en PowerShell, te dará un error de The token '&&' is not a valid statement separator; a la inversa, si ejecutas irm en CMD, te dará un error de 'irm' is not recognized. Cambia al comando correspondiente cuando veas estos errores.

Además, para el entorno nativo de Windows, se recomienda instalar Git for Windows, que proporciona Git Bash a Claude Code; si no lo instalas, usará PowerShell para ejecutar comandos (también funciona, solo que algunos scripts de Bash están limitados). WSL no lo necesita.

¿Elegir WSL o Nativo en Windows?

Si estás desarrollando herramientas de Linux o quieres usar la función de sandboxing, usa WSL. Tabla comparativa oficial:

Opción	Qué se necesita	Soporta Sandboxing	Cuándo usarlo
Windows Nativo	Nada (Git for Windows opcional)	❌	Proyectos y herramientas nativos de Windows
WSL 2	Habilitar WSL 2	✅	Herramientas de Linux o si quieres usar sandboxing
WSL 1	Habilitar WSL 1	❌	La alternativa cuando WSL 2 no está disponible

Si eliges WSL, ejecuta el script curl para macOS/Linux anterior en la terminal de WSL, es para instalarlo en WSL, no en PowerShell.

¿No quieres tocar la terminal? Hay otras formas

Además del script oficial, hay varias alternativas, aquí tienes una comparación para que elijas según tus necesidades:

Método de instalación	Comando	Actualización automática	Mi sugerencia
Script oficial	curl ... | bash	✅ En segundo plano	Primera opción, sin preocupaciones
Homebrew (macOS)	brew install --cask claude-code	❌ Manual	Personas que ya usan brew en gran medida para administrar software
WinGet (Windows)	winget install Anthropic.ClaudeCode	❌ Manual	Personas que están acostumbradas a usar WinGet
npm	npm install -g @anthropic-ai/claude-code	❌ Manual	Considerar solo como último recurso, requiere instalar Node.js 18+ primero

Algunas trampas a tener en cuenta:

• Homebrew tiene dos cask: claude-code es la versión estable (una semana de retraso, salta las versiones con regresiones importantes), claude-code@latest es la última versión; las actualizaciones corresponden a brew upgrade claude-code / brew upgrade claude-code@latest.
• WinGet no se actualiza automáticamente: Necesita que ejecutes periódicamente de forma manual winget upgrade Anthropic.ClaudeCode.
• Nunca agregues sudo a npm. La advertencia oficial establece claramente que sudo npm install -g causará problemas de permisos y riesgos de seguridad; esta es exactamente la trampa más común mencionada al principio. Si encuentras un error de permisos, la solución correcta es cambiar al script oficial. La actualización de npm también debe usar npm install -g ...@latest, no uses npm update -g.

💡 Resumen en una frase: Elige el script oficial a ciegas y acertarás, resuelve todo con un solo curl (o irm de Windows), y viene con actualización en segundo plano; npm es el peor plan, y nunca uses sudo.

---

03 Verifica si se instaló correctamente

No te apresures a usarlo después de la instalación, dedica diez segundos a confirmarlo. Abre una nueva ventana de terminal y escribe:

claude --version

El resultado esperado es un número de versión, similar a (el número que veas se actualizará, es normal):

2.1.81 (Claude Code)

Ver el número de versión = instalación exitosa. Si te dice command not found: claude o 'claude' is not recognized en Windows, no te apresures a reinstalar; en el 90% de los casos el PATH no está bien configurado (el directorio de instalación no ha ingresado a la ruta de búsqueda del sistema), hay una solución en la sección 06.

Si quieres más detalles, el equipo oficial también proporcionó un comando de diagnóstico:

claude doctor

Enumerará el estado de instalación, la configuración y los resultados de la última actualización. Cuando instales en una máquina nueva o experimentes problemas, tu primera reacción debería ser ejecutar claude doctor; es mucho más rápido que adivinar a ciegas.

💡 Resumen en una frase: Si claude --version muestra el número de versión, entonces está listo; si hay algo raro, claude doctor es tu primera herramienta de diagnóstico.

---

04 Iniciar sesión: Haz que te reconozca

El Claude Code instalado sigue siendo una "cáscara vacía" que "no te conoce", tienes que iniciar sesión y vincular tu cuenta para que empiece a trabajar. Inícialo en el directorio de tu proyecto:

claude

Al iniciarlo por primera vez, te guiará automáticamente para iniciar sesión, o puedes activarlo manualmente después de ingresar a la interfaz:

/login

A continuación, abrirá una página del navegador para que la autorices, y una vez autorizada, volverás a la terminal y habrás iniciado sesión. Las credenciales se guardan localmente, por lo que no es necesario volver a iniciar sesión la próxima vez que lo inicies. Si cambias de cuenta, solo vuelve a ejecutar /login.

¿Qué hacer si el inicio de sesión se atasca?

El caso más común: El navegador no aparece automáticamente, o estás iniciando sesión en un servidor remoto / WSL / SSH: el navegador puede estar abierto en otra máquina y la devolución de llamada no puede regresar. La solución oficial es muy sencilla:

En la interfaz de indicación de inicio de sesión, presiona c, copia esa cadena de URL de OAuth (Autorización Abierta), pégala manualmente en el navegador para abrirla, y cuando termines de iniciar sesión y muestre un código (code), pega de nuevo ese código en la terminal.

Es muy fácil sufrir esta desventaja al configurar Claude Code en servidores en la nube, esperando en vano a que aparezca el navegador; el entorno remoto tiene que ir por esta ruta de "copiar URL para abrir manualmente". Si incluso pegar no funciona, hay un comando de respaldo más confiable:

claude auth login

Lee el código que pegaste de la entrada estándar, específicamente para las terminales donde los avisos interactivos no permiten pegar.

Una trampa de inicio de sesión oculta

Después de iniciar sesión, te dice This organization has been disabled, pero la suscripción está claramente bien; lo más probable es que haya un viejo ANTHROPIC_API_KEY sobrante en la configuración de la shell, que ha anulado las credenciales de tu suscripción.

Cuando hay una clave de API en las variables de entorno, Claude Code preferirá usar la clave en lugar de la suscripción. La solución es limpiarla:

unset ANTHROPIC_API_KEY
claude

Para solucionarlo permanentemente, ve a buscar en ~/.zshrc, ~/.bashrc o ~/.profile y elimina esa línea de export ANTHROPIC_API_KEY=.... Después de ingresar a Claude Code, puedes usar /status para confirmar qué método de inicio de sesión se está utilizando actualmente.

💡 Resumen en una frase: Iniciar claude guiará automáticamente el inicio de sesión. Para entornos remotos/WSL, recuerda "presionar c para copiar la URL y abrirla manualmente"; si el inicio de sesión informa que la organización está deshabilitada, primero verifica si hay una antigua clave de API en las variables de entorno.

---

05 Actualización y desinstalación

Actualización

Si usaste el script oficial para instalar, no tienes que hacer nada: se actualiza automáticamente en segundo plano y la próxima vez que lo inicies será la nueva versión. Si quieres actualizar de inmediato:

claude update

Para saber si la actualización tuvo éxito, usa nuevamente claude doctor. El canal de actualización se puede seleccionar (escrito en settings.json, o usando /config dentro de Claude Code):

{
  "autoUpdatesChannel": "stable"
}

• "latest" (predeterminado): Obtén nuevas funciones tan pronto como se publiquen
• "stable": Usa la versión de hace aproximadamente una semana, omitiendo lanzamientos con regresiones importantes; elige esto si buscas estabilidad

Si no quieres la actualización automática, simplemente establece "DISABLE_AUTOUPDATER": "1" en env dentro de settings.json (solo detiene la verificación en segundo plano, la actualización manual con claude update todavía funcionará). Las instalaciones a través de Homebrew / WinGet / apt no se actualizan automáticamente de forma predeterminada, y tendrás que ejecutar manualmente el comando de actualización correspondiente (mencionado en las advertencias de trampas anteriores).

Desinstalación

Desinstálalo de acuerdo con la forma en que lo instalaste originalmente. Si lo instalaste con el script oficial:

macOS / Linux / WSL:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Windows PowerShell:

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Para otros métodos, usa el correspondiente: Homebrew usa brew uninstall --cask claude-code, WinGet usa winget uninstall Anthropic.ClaudeCode, y npm usa npm uninstall -g @anthropic-ai/claude-code.

Nota: Todo lo anterior solo elimina el programa en sí; las configuraciones, las autorizaciones y el historial de sesiones aún permanecen en ~/.claude/. Si después de desinstalar, el comando claude todavía puede ejecutarse, lo más probable es que tengas una segunda instalación o un alias de shell dejado por una versión antigua (la sección 06 te enseñará a averiguarlo).

Si quieres hacer una limpieza completa (este paso es irreversible, las configuraciones / autorizaciones / configuraciones MCP / el historial de sesiones desaparecerán por completo):

# Configuraciones y estado del usuario global
rm -rf ~/.claude
rm ~/.claude.json

# Configuraciones locales del proyecto actual (se ejecuta en el directorio del proyecto)
rm -rf .claude
rm -f .mcp.json

Recordatorio: La extensión de VS Code, el plugin de JetBrains y la App de escritorio también escribirán cosas en ~/.claude/, y mientras estén instalados, este directorio se reconstruirá; para eliminarlo por completo, primero debes desinstalarlos.

💡 Resumen en una frase: Con la instalación del script oficial, la actualización es automática en segundo plano, o se usa claude update para forzarla manualmente; la desinstalación debe corresponder al método de instalación original, los archivos de configuración deben eliminarse por separado y la eliminación es irreversible.

---

06 Referencia rápida de errores: Las trampas que pisará el 90% de los principiantes

Los errores durante la instalación de esta herramienta son casi inevitables, pero la gran mayoría tiene una solución estándar. He compilado los errores más frecuentes de la documentación oficial en una tabla de referencia rápida: primero diagnostica el problema y luego aplica el remedio, no reinstales a la primera señal de un error.

Error que ves	Razón real	Cómo solucionarlo
command not found: claude	El directorio de instalación no está en el PATH	Agrega ~/.local/bin al PATH (ver más abajo)
syntax error near unexpected token '<'	El script de instalación devolvió HTML en lugar de un script	Principalmente un problema de red/región; cambia a Homebrew/WinGet o inténtalo más tarde
irm is not recognized	Ejecutaste un comando de PowerShell en CMD	Cambia al comando de instalación de CMD o abre PowerShell
'&&' is not valid	Ejecutaste un comando de CMD en PowerShell	Cambia al comando irm de PowerShell
bash is not recognized	Ejecutaste un comando de Mac/Linux en Windows	Cambia al comando irm de PowerShell
Instalación en Linux muestra Killed	Falta de memoria (Proceso eliminado por OOM)	Agrega espacio de intercambio (swap) (ver más abajo), Claude Code requiere 4GB+ RAM
Error loading shared library	El instalador juzgó mal el tipo de libc del sistema y descargó la variante incorrecta	Consulta la solución de problemas de musl/glibc en la documentación oficial
Después de iniciar sesión, 403 Forbidden	Suscripción no válida / La cuenta no tiene permisos	Verifica el estado de la suscripción o confirma que la cuenta de Console tiene el rol correspondiente
App unavailable in region	Tu región no es compatible	Consulta los países/regiones compatibles

Vamos a profundizar en dos de los más frecuentes.

Trampa 1: command not found: claude (La más común)

Si ejecutas claude y dice que no encuentra el comando: no es que no se haya instalado, sino que el directorio de instalación no se ha agregado a la ruta de búsqueda del sistema (PATH).

Analogía: PATH es como el registro de números de las casas en el sistema. Instalar el programa es como construir una casa, pero el sistema solo la buscará en las direcciones registradas en el "registro de números de las casas". La casa de claude está construida en ~/.local/bin/; si esa dirección no está registrada, naturalmente no se podrá encontrar.

Solución (macOS por defecto es Zsh):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Linux a menudo usa Bash por defecto, solo cambia ~/.zshrc por ~/.bashrc. Después de cambiarlo, verifica:

claude --version

Si aparece el número de versión, está arreglado. Para los usuarios de Windows, agreguen %USERPROFILE%\.local\bin a la variable de entorno PATH del usuario y luego reinicien la terminal.

Trampa 2: Encontrar instalaciones múltiples que "se pelean"

Si primero instalaste con npm y luego usaste el script oficial para instalarlo de nuevo, es posible que existan varios claude al mismo tiempo, los números de versión no coincidirán y el comportamiento será extraño. Primero verifica cuántos hay en el PATH:

which -a claude

Si hay más de uno en la lista, solo conserva el del script oficial (~/.local/bin/claude) y elimina el resto:

# Desinstalar la instalación global de npm
npm uninstall -g @anthropic-ai/claude-code

# Eliminar la antigua instalación local de npm
rm -rf ~/.claude/local

En muchos casos, al ejecutar which -a claude, descubrirás que npm y el método nativo instalaron uno cada uno; eliminar el de npm y ordenar el PATH restaurará inmediatamente la paz.

💡 Resumen en una frase: Para los errores, primero consulta la tabla para encontrar la causa, no reinstales por reflejo condicionado; si no puedes encontrar el comando, la mayoría de las veces es un problema de PATH, y si el comportamiento es extraño, la mayoría de las veces es por múltiples instalaciones que entran en conflicto, y which -a claude lo aclarará todo.

---

07 Práctica: Ejecutando todo desde cero por primera vez

Tenerlo instalado no cuenta; ejecutar el proceso real para confirmar que la cadena está conectada sí cuenta. Este flujo mínimo no depende de un proyecto existente, se puede hacer creando un directorio vacío.

Paso uno, crea un directorio de prueba y entra en él, y luego inicia Claude Code:

mkdir claude-test && cd claude-test
claude

El primer inicio te guiará para que inicies sesión (sigue la sección 04) y, después de iniciar sesión, verás la interfaz de bienvenida.

Paso dos, escribe /help en el cuadro de entrada para ver qué comandos hay:

/help

Expectativa: Aparecerá una lista de los comandos disponibles y descripciones de las funciones. Si solo escribes /, también aparecerá el autocompletado para todos los comandos.

Paso tres, pídele que haga algo real, solo da una instrucción en lenguaje sencillo (no es necesario recordar formatos de comandos):

Escribe una función para imprimir hola mundo en el archivo test.py

Comportamiento esperado: Claude Code primero te mostrará el código a modificar como un diff (comparación de diferencias), y solo escribirá en el archivo cuando lo confirmes (seleccionando yes). Este es su flujo de trabajo principal: dar una propuesta primero, esperar tu aprobación y luego actuar; no modificará tus cosas en secreto.

Después de la confirmación, habrá un test.py más en el directorio. Para salir:

exit

Al llegar a este paso, habrás completado todo el proceso de "Instalar → Iniciar sesión → Dar instrucción → Modificar archivo → Tú confirmas". La primera vez que lo ves escribir código por sí mismo y detenerse para esperar tu aprobación, te da una sensación muy real de "esta cosa realmente puede hacer el trabajo"; la primera vez que se completa el proceso, es normal sentir un poco de emoción.

Esta imagen conecta los cuatro pasos anteriores en una sola línea: desde iniciar claude, iniciar sesión, /help para ver comandos y dar instrucciones en lenguaje sencillo, hasta el eslabón más crítico: Primero te muestra el diff, espera a que apruebes (yes) antes de escribir el archivo; si dices que no (no), no escribe y lo intentará de nuevo después de ajustar, en todo el proceso, nunca modificará tus cosas en secreto.

💡 Resumen en una frase: Se puede ejecutar todo el proceso simplemente creando un directorio vacío: Inicia sesión con claude, usa /help para ver los comandos, da instrucciones en lenguaje sencillo, mira el diff y haz clic en yes; esta rutina de "dar una propuesta primero y luego actuar" es su ritmo más central.

---

08 Resumen

Este artículo ha repasado completamente el "instalarlo y usarlo":

• Confirma tres cosas antes de la instalación: la versión del sistema es suficiente, la cuenta es de nivel de pago o Console, elige CLI para el uso.
• Reconoce el script oficial: Mac/Linux/WSL usa curl, Windows distingue entre PowerShell (irm) y CMD; npm es el peor plan, y nunca uses sudo.
• Verifica con claude --version, haz un diagnóstico con claude doctor; si el inicio de sesión informa de una organización deshabilitada, comprueba primero si hay restos de ANTHROPIC_API_KEY.
• Busca primero la causa en la tabla de errores: si no puedes encontrar el comando, verifica el PATH; si el comportamiento es extraño, verifica si hay múltiples instalaciones.

Ahora deberías poder instalar Claude Code de forma independiente en tu propia máquina, iniciar sesión, ejecutar el primer ejemplo y saber dónde buscar cuando encuentres errores comunes.

Siguiente artículo 03 · Cómo funciona Claude Code: Levanta la tapa y mira el interior: esa oración de "escribe una función de hola mundo", ¿cómo se transformó de una frase a una modificación precisa del archivo? Detrás hay un mecanismo llamado "ciclo de agente"; solo entendiéndolo, podrás decir que realmente sabes cómo usar Claude Code, y no solo saber escribir comandos.

Una pregunta para dejar: cuando acabas de decirle que escribiera test.py, ¿primero miró qué archivos había en el directorio o empezó a escribir directamente? Esa diferencia es precisamente el punto de partida del próximo artículo.

---

Una vez instalado, solo has obtenido la herramienta, saber cómo usar su "mentalidad" es la verdadera habilidad; nos vemos en el próximo artículo.

---

Lecturas recomendadas

• Plugins: Empaqueta un montón de pequeñas configuraciones con un clic
• Manual de referencia de Plugins: Empaqueta tus propias configuraciones en un paquete distribuible
• Configuración de desarrollo: Ajusta el "entorno de trabajo" de Claude