Instalar Claude Code: Native vs npm, corregir PATH y primer inicio
Guía práctica para instalar Claude Code: comparativa entre Native Install y npm, verificación de binarios, resolución de errores de PATH y command not found, y ejecución de tu primera sesión de programación segura.
Índice
Para la instalación nativa (Native Install) de Claude Code, el entorno de ejecución de Node.js no es necesario en absoluto. Actualmente, el instalador de npm requiere Node.js 22 o superior, pero el archivo binario instalado funciona de manera completamente independiente del runtime de Node. La documentación oficial de Anthropic recomienda explícitamente utilizar Native Install (para más detalles, consulta la guía de instalación). Para trabajar con el agente de código en la terminal, el desarrollador debe elegir un método de instalación, ejecutar el comando adecuado en una shell compatible y asegurarse de que el sistema operativo reconozca correctamente el archivo ejecutable. Cuando surgen errores al invocar el comando, identificar la causa raíz depende de distinguir con precisión entre una distribución nativa autónoma y una instalación mediante gestor de paquetes.
Native vs npm: límites arquitectónicos y el rol de Node.js
La documentación oficial de Anthropic recomienda Native Install (guía de instalación). En esta modalidad, el entorno de ejecución Node.js no es necesario: el instalador descarga un binario autónomo precompilado que nunca interactúa con Node durante su ejecución.
La instalación mediante el paquete global npm se mantiene como una alternativa disponible. Actualmente, el instalador de npm requiere Node.js 22 o superior. Si ejecutas la instalación en una versión anterior de Node.js, npm emitirá una advertencia EBADENGINE, pero el proceso suele completarse con éxito: el paquete descarga un binario precompilado específico para la plataforma y crea un enlace simbólico hacia él. En tiempo de ejecución, el binario de Claude Code instalado tampoco se ejecuta dentro de Node.js.
Por lo tanto, la afirmación de que ejecutar Claude Code requiere siempre Node.js es técnicamente incorrecta. Comprobar la versión de Node.js solo es necesario cuando decides instalarlo intencionadamente a través de npm.
Comandos de instalación para sistemas compatibles
Para garantizar una instalación correcta, ejecuta el script oficial correspondiente a tu sistema operativo y entorno de shell.
macOS, Linux y WSL (Bash / Zsh)
curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell
irm https://claude.ai/install.ps1 | iexWindows Símbolo del sistema (CMD)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdInstalación alternativa mediante npm
npm install -g @anthropic-ai/claude-codeImportante: no ejecutes este comando con
sudo npm install -g. Instalar paquetes con privilegios de superusuario provoca conflictos de permisos sobre los archivos en tu directorio de inicio y genera riesgos de seguridad.
En la plataforma nativa de Windows, la presencia de Git for Windows es ahora opcional. Si Git for Windows está instalado, el agente podrá ejecutar comandos de Bash a través de Git Bash; si no está disponible, Claude Code recurre a sus herramientas integradas de PowerShell.
Verificación de la instalación
Una vez completado el instalador, verifica que el archivo binario esté accesible en tu entorno:
claude --versionUna salida de versión correcta confirma que el binario se ha descargado, descomprimido y registrado en tu entorno. Ten en cuenta que visualizar la versión con éxito solo verifica el funcionamiento del binario en sí; no indica que el cliente esté autenticado ni que pueda realizar peticiones al modelo.
Para realizar una auditoría completa del entorno, ejecuta la utilidad de diagnóstico:
claude doctorEl comando claude doctor audita tu configuración local: comprueba el estado de los archivos de configuración, los permisos del sistema de archivos y las dependencias del sistema, identificando posibles problemas de configuración sin iniciar una sesión interactiva de código.
Diagnóstico: cómo resolver el error command not found
Si la terminal indica que no se encuentra el comando claude (o en Windows aparece un mensaje advirtiendo que el comando no se reconoce como un comando interno o externo), sigue este flujo secuencial de diagnóstico:
[Ошибка вызова: claude не найден]
│
▼
[Шаг 1: Открыть новый сеанс терминала]
│
Помогло? ──Да──> Завершено
│ Нет
▼
[Шаг 2: Проверить физическое наличие бинарного файла на диске]
│
Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку
│ Да
▼
[Шаг 3: Проверить тип установки и PATH]
│
┌───────┴────────────────────────┐
▼ ▼
[Native Install] [npm Install]
Проверить PATH: Проверить PATH через npm prefix -g:
- Unix: ~/.local/bin - Unix: <prefix>/bin
- Win: %USERPROFILE%\.local\bin - Win: <prefix>
(Не переустанавливать только из-за PATH)El árbol de decisión anterior detalla la progresión del diagnóstico:
- Error inicial:
[Ошибка вызова: claude не найден]se traduce como[Error de llamada: claude no encontrado]. - Paso 1:
[Шаг 1: Открыть новый сеанс терминала]te pide abrir una nueva sesión de terminal. Si resolvió el problema (Помогло? ──Да──> Завершено/¿Ayudó? ──Sí──> Completado), el proceso concluye. Si no lo resolvió (Нет/No), continúa al Paso 2. - Paso 2:
[Шаг 2: Проверить физическое наличие бинарного файла на диске]comprueba la existencia física del binario en disco. Si no está (Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку/¿Archivo encontrado? ──No──> Error de descarga o permisos; repetir instalación), vuelve a ejecutar el instalador. Si está presente (Да/Sí), avanza al Paso 3. - Paso 3:
[Шаг 3: Проверить тип установки и PATH]evalúa el método de instalación y las rutas en PATH:- Para Native Install, revisa PATH (
Проверить PATH:):~/.local/binen Unix o%USERPROFILE%\.local\binen Windows. - Para npm Install, comprueba PATH mediante
npm prefix -g(Проверить PATH через npm prefix -g:):<prefix>/binen Unix o<prefix>en Windows. - La advertencia inferior
(Не переустанавливать только из-за PATH)señala: (No reinstalar solo por problemas de PATH).
- Para Native Install, revisa PATH (
1. Abre una nueva sesión de terminal
Los scripts de instalación introducen cambios en los archivos de configuración de la shell (.bashrc, .zshrc) o en las variables de entorno de usuario en Windows. Las ventanas de terminal abiertas previamente no cargan estas modificaciones sobre la marcha. Cierra por completo la sesión actual y abre una ventana nueva.
2. Comprueba la ruta física del archivo
En una instalación nativa (Native Install), el archivo ejecutable se ubica por defecto en rutas estándar (a menos que hayan sido redefinidas):
- en macOS, Linux y WSL:
~/.local/bin/claude(las versiones se almacenan en~/.local/share/claude); - en Windows:
%USERPROFILE%\.local\bin\claude.exe.
Estas rutas son valores predeterminados estándar, no ubicaciones inmutables si existen configuraciones personalizadas del usuario. Si el archivo no está en el directorio esperado, es posible que el proceso de instalación haya fallado debido a un corte de red o a la falta de permisos de escritura.
3. Ejecuta comandos de diagnóstico de la shell
Para averiguar cómo detecta la shell el archivo ejecutable, utiliza las herramientas nativas del sistema:
- en Zsh / Bash: ejecuta
command -v claudeotype -a claude; - en PowerShell: invoca
Get-Command claudey también la utilidadwhere.exe claude; - en CMD: utiliza el comando
where claude.
4. Separa la resolución de PATH para Native y npm
Un error frecuente consiste en intentar reconfigurar las rutas de Node.js ante un fallo en Native Install.
- Si utilizaste Native Install, los directorios de Node.js y
npm prefix -gno guardan relación con el problema. Debes verificar y añadir a la variablePATHel directorio~/.local/bin(en sistemas Unix) o%USERPROFILE%\.local\bin(en Windows). - Para instalaciones mediante
npm install -g, el directorio de ejecutables se determina con el comandonpm prefix -g:- en sistemas tipo Unix (macOS, Linux, WSL), el ejecutable se ubica en
<prefix>/bin; - en Windows, el archivo ejecutable se encuentra directamente en la raíz de
<prefix>. Los comandosnpm bin -gynpm root -gno apuntan a la ruta correcta de los ejecutables.
- en sistemas tipo Unix (macOS, Linux, WSL), el ejecutable se ubica en
Si el binario existe en el disco pero la terminal no encuentra el comando, revisa primero el PATH y la resolución de la shell. Si ejecutar el binario mediante su ruta absoluta completa también falla, examina el texto exacto del error y consulta la documentación oficial de resolución de problemas: es posible que se requiera revisar permisos de acceso, compatibilidad del binario con la plataforma o una instalación incompleta. No reinstales a ciegas únicamente por un error de command not found.
Primer inicio y exploración segura
Una vez confirmada la disponibilidad del comando, accede al directorio de un proyecto pequeño e inicia una sesión:
cd /path/to/test-project
claudeEn el primer arranque, la interfaz te solicitará completar el procedimiento estándar de autenticación mediante el navegador. Dentro de una sesión activa, el comando /status permite verificar el directorio de trabajo actual, el identificador de la cuenta y el modelo configurado.
Para una primera toma de contacto, ejecuta un ejercicio introductorio no destructivo:
Объясни назначение основных файлов в проекте. Не изменяй файлы, не устанавливай зависимости и не выполняй команды в терминале.(Traducción del prompt de prueba: “Explica el propósito de los archivos principales del proyecto. No modifiques archivos, no instales dependencias y no ejecutes comandos en la terminal.”)
La respuesta esperada es que el agente enumere los archivos principales y explique su función sin generar diffs ni realizar modificaciones en los archivos. Tras finalizar la tarea, ejecuta el comando git diff en otra terminal para confirmar que la base de código permanece intacta.
Es fundamental comprender que una instrucción en el prompt es solo una guía en lenguaje natural proporcionada al modelo, no un modo de ejecución forzado (enforced mode) ni un entorno de aislamiento tipo sandbox en el sistema operativo. Si un repositorio requiere restringir de forma estricta la edición automática de código, utiliza el modo de planificación:
claude --permission-mode planEn el modo plan, el agente solo lee archivos y utiliza comandos de shell de solo lectura de manera predeterminada, sin editar el código fuente; sin embargo, este modo no constituye un sandbox aislado a nivel de sistema operativo: cuando la ejecución automática está activa, pueden ejecutarse comandos aprobados por el clasificador (no debe asumirse un aislamiento estricto a nivel de sistema; información confirmada por la documentación con fecha de 2026-09-15).
Para consultar la descripción detallada de las políticas de confirmación de acciones, revisa la guía de permisos. Para salir de la sesión interactiva del agente, presiona Ctrl+D.
Conexión de un proveedor de API independiente
Instalar la herramienta CLI y configurar el proveedor de modelos son dos pasos operativos independientes. Si en lugar de la cuenta estándar prefieres utilizar una conexión a través de una pasarela compatible con Anthropic de terceros, los parámetros de acceso se configuran por separado tras verificar el funcionamiento local del CLI.
En concreto, el proveedor de API independiente BetterToken proporciona a los desarrolladores una API Key personal, y el volumen de peticiones a los modelos, el consumo de tokens y la facturación se monitorizan desde el panel de control Dashboard. Las instrucciones para exportar las variables de entorno necesarias y definir la dirección base de la API se detallan en la documentación de BetterToken sobre Claude Code. La descarga, actualización y ejecución local del archivo binario continúan realizándose mediante los mecanismos estándar del CLI descritos a lo largo de esta guía.
