2. Instalación de Qwen Code

Objetivo del tema

Instalar Qwen Code correctamente, comprender qué requisitos exige el entorno, elegir el método de instalación más conveniente y verificar que el primer arranque quede listo para continuar con la autenticación y el uso interactivo.

Este contenido se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en la guía de inicio rápido de Qwen Code Docs, la documentación de GitHub y la sección de sandbox, que además confirma el uso del comando qwen --version tras la instalación.

2.1 Qué necesitamos antes de instalar

La documentación de Quickstart indica tres puntos de partida muy concretos:

• Una terminal o consola disponible.
• Un proyecto de código sobre el cual trabajar.
• Una cuenta de Qwen Code o Qwen asociada al servicio.

Además, si elegimos la instalación manual con npm, se requiere Node.js 20 o superior. Este dato es importante porque versiones anteriores de Node pueden provocar errores en la instalación o en la ejecución del CLI.

El requisito de Node.js 20+ no es opcional en la instalación manual. Si la versión local es más antigua, lo correcto es actualizar primero el entorno y recién después instalar Qwen Code.

2.2 Métodos oficiales de instalación

La guía oficial presenta dos caminos principales para instalar Qwen Code:

1. Instalación rápida recomendada por script.
2. Instalación manual usando npm, o Homebrew en sistemas compatibles.

Comparación entre métodos de instalación

Método	Cuándo conviene	Observaciones
Instalación rápida	Cuando se quiere tener Qwen Code listo con la menor fricción posible.	Es la opción recomendada por la documentación oficial.
Instalación manual con npm	Cuando ya se trabaja con Node.js y se desea más control sobre el entorno.	Exige Node.js 20 o superior.
Homebrew	Cuando se usa macOS o Linux con Homebrew y se prefiere gestionar herramientas desde ese ecosistema.	Es una alternativa cómoda, pero no reemplaza la necesidad de verificar el entorno después.

2.3 Instalación rápida en Linux y macOS

La documentación oficial marca este camino como Quick Install (Recommended) para Linux y macOS:

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash

Este comando descarga y ejecuta el instalador oficial. La ventaja principal es la rapidez: en un solo paso prepara la herramienta para usarla desde la terminal.

Conviene entender bien qué hace este tipo de comando:

• curl -fsSL: descarga el script desde la URL oficial.
• | bash: envía el contenido descargado al intérprete Bash para ejecutarlo.
• Resultado esperado: Qwen Code queda instalado y accesible mediante el comando qwen.

Como regla práctica, este método conviene cuando se quiere seguir exactamente el flujo recomendado por la propia documentación del producto.

2.4 Instalación rápida en Windows

Para Windows, la guía oficial indica ejecutar el instalador rápido desde CMD como administrador:

curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat

La lógica es similar a la del instalador de Linux/macOS, pero en este caso se descarga un archivo por lotes y luego se ejecuta.

• Se guarda el instalador en la carpeta temporal del sistema.
• Luego se ejecuta el archivo .bat.
• Al finalizar, conviene cerrar y volver a abrir la terminal.

La documentación oficial recomienda reiniciar la terminal después de instalar, para asegurar que las variables de entorno y la detección del comando queden actualizadas.

2.5 Instalación manual con npm

Si preferís un enfoque más tradicional o ya trabajás con Node.js en tu equipo, la instalación manual es directa:

npm install -g @qwen-code/qwen-code@latest

Acá el punto crítico es el requisito previo:

node --version
npm --version

Si el sistema no devuelve una versión de Node.js 20 o superior, primero hay que actualizar Node. Instalar el paquete sobre una base obsoleta es una receta casi segura para tener problemas después.

Este método tiene varias ventajas:

• Mayor control técnico: sabés exactamente qué gestor de paquetes interviene.
• Mejor integración con un entorno ya orientado a JavaScript o TypeScript.
• Facilidad para actualizar desde npm.

2.6 Instalación con Homebrew

La guía de Quickstart también documenta la instalación con Homebrew para macOS y Linux:

brew install qwen-code

Esta opción resulta especialmente cómoda para quienes ya administran herramientas de línea de comandos con Brew. El criterio, sin embargo, sigue siendo el mismo que con cualquier otro método: una vez instalado, hay que verificar que el comando qwen responda correctamente.

2.7 Cómo verificar que la instalación fue exitosa

La verificación básica recomendada en la documentación consiste en pedir la versión instalada:

qwen --version

Si la instalación quedó bien, la terminal mostrará el número de versión del CLI. Si no reconoce el comando, generalmente el problema está en una de estas causas:

• La instalación falló y no se completó correctamente.
• La terminal no se reinició después de instalar.
• El ejecutable no quedó en una ruta incluida en el PATH.
• Node.js o npm no estaban disponibles correctamente en el caso de la instalación manual.

La verificación no es un paso accesorio. Antes de seguir con autenticación o uso del agente, primero hay que asegurarse de que qwen responde desde la terminal sin errores.

2.8 Primer arranque de Qwen Code

Una vez instalado, el primer arranque interactivo se hace con el comando más simple del flujo:

qwen

La guía oficial indica que, al abrir una sesión por primera vez, Qwen Code puede solicitar autenticación. También menciona que existe el comando qwen auth para configurar la autenticación fuera de la sesión, y qwen auth status para consultar el estado actual.

qwen auth
qwen auth status

Este primer arranque cumple varias funciones a la vez:

• Confirma que el ejecutable está operativo.
• Inicia la interacción con la cuenta del servicio.
• Prepara el entorno para trabajar dentro de una carpeta de proyecto.

2.9 Dónde conviene ejecutar Qwen Code

Aunque el comando puede lanzarse desde distintas ubicaciones, la recomendación práctica es iniciarlo dentro de la carpeta del proyecto con el que se va a trabajar. De ese modo, el agente puede interpretar el contexto de archivos desde el comienzo.

cd ruta/del/proyecto
qwen

Esto es importante por una razón pedagógica y técnica: Qwen Code no fue pensado para trabajar en el vacío, sino sobre un contexto concreto. Cuanto mejor ubicada esté la sesión, más útiles serán las respuestas y propuestas de cambio.

2.10 Problemas frecuentes en la instalación

En la práctica, los problemas de instalación suelen concentrarse en unos pocos puntos repetidos. Conviene reconocerlos desde el principio:

Problemas habituales y su causa probable

Problema	Causa probable	Primer paso razonable
qwen no se reconoce	La terminal no se reinició o el ejecutable no quedó en el PATH.	Cerrar y abrir la terminal; luego volver a probar qwen --version.
Falla la instalación con npm	Node.js desactualizado o entorno npm mal configurado.	Verificar node --version y confirmar Node.js 20+.
El script rápido no funciona	Permisos insuficientes, restricción del entorno o shell inadecuada.	Revisar la consola usada y volver a intentar desde el entorno recomendado.
La herramienta arranca pero no autentica	El CLI está bien instalado, pero falta resolver la cuenta o el método de login.	Usar qwen auth o iniciar qwen y seguir el flujo de autenticación.

La lógica correcta es resolver primero instalación, luego verificación y recién después autenticación. Mezclar esos pasos suele volver más confuso el diagnóstico.

2.11 Qué método conviene elegir

No hay un único camino perfecto para todos. La elección depende del entorno y del grado de control que quieras tener:

• Elegí instalación rápida si querés seguir el camino oficial con la menor fricción posible.
• Elegí npm si trabajás habitualmente con Node.js y preferís administrar el CLI desde ese ecosistema.
• Elegí Homebrew si ya centralizás tus herramientas de terminal con Brew en macOS o Linux.

Lo importante no es solo instalar, sino dejar un entorno entendible y mantenible. Para un curso, eso significa que el alumno debe saber qué instaló, cómo comprobarlo y dónde empezar a usarlo.

2.12 Síntesis final

Instalar Qwen Code no es complejo, pero conviene hacerlo con criterio. La documentación oficial recomienda la instalación rápida, ofrece una alternativa manual con npm y también contempla Homebrew en sistemas compatibles.

En este tema vimos las ideas centrales:

1. La instalación manual con npm requiere Node.js 20 o superior.
2. Linux/macOS y Windows tienen instaladores rápidos oficiales distintos.
3. Después de instalar hay que verificar con qwen --version.
4. El primer arranque interactivo se hace con qwen.
5. La autenticación y la configuración inicial continúan a partir de un entorno ya validado.

Con esto ya tenemos la base práctica para avanzar al siguiente tema: la autenticación en Qwen Code y la preparación de la cuenta para usar el agente sin fricciones.