Tutoriales

Qwen CLI: Cómo instalar y usar Qwen Code (2026)

Qwen CLI (Qwen Code) es un agente de codificación de terminal de código abierto. Aquí tienes cómo instalarlo y cómo configurarlo ahora que el nivel gratuito de OAuth ha desaparecido.

TL;DR

Qwen CLI (oficialmente Qwen Code) es el agente de programación en terminal open-source de Alibaba: un fork de Gemini CLI ajustado para modelos Qwen. Instálalo con npm install -g @qwen-code/qwen-code@latest en Node.js 22+.
El gran cambio que la mayoría de las guías pasan por alto: el nivel gratuito de Qwen OAuth se discontinuó el 2026-04-15. El antiguo "2,000 solicitudes gratis al día" ya no funciona; ahora necesitas un proveedor de API.
Configúralo apuntándolo a cualquier endpoint compatible con OpenAI mediante tres variables de entorno: OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL. Esa es toda la configuración.
Un solo endpoint puede ejecutar Qwen *y* otros modelos. Apunta OPENAI_BASE_URL a [Velokey](https://api.velokey.ai) y puedes usar Qwen Code con qwen3.7-max, GPT, Claude o GLM con una sola clave.

¿Qué es Qwen CLI (Qwen Code)?

Qwen CLI es el nombre común de Qwen Code, un agente de programación con IA open-source que se ejecuta en tu terminal, creado por el equipo de Qwen en Alibaba. Lee y edita tu base de código, ejecuta comandos y trabaja de forma agéntica en tareas, con una forma similar a Claude Code o Gemini CLI. De hecho, empezó como un fork de Gemini CLI, adaptado con prompts y analizadores ajustados para los modelos de Qwen.

Hay dos cosas que conviene saber antes de instalarlo. Primero, el paquete se llama @qwen-code/qwen-code, así que "qwen cli", "qwen-cli" y "qwen code cli" apuntan todos a la misma herramienta. Segundo —y esto confunde a mucha gente— no está bloqueado a los servidores de Qwen. Habla el protocolo compatible con OpenAI, así que puedes ejecutarlo contra la API de Qwen, OpenRouter, un modelo local o una gateway. Lo cual importa más que nunca ahora, porque la ruta gratuita cambió.

¿Cómo instalo Qwen Code CLI?

Instala Qwen Code globalmente con npm, en Node.js 22 o posterior:

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

Si estás en macOS, Homebrew también funciona (brew install qwen-code), y hay instaladores independientes para Linux y Windows. Esto es lo que realmente importa durante la instalación:

Requisito	Detalle
Node.js	22+ — la UI de terminal (Ink 7 / React 19) lo necesita; Node 20 suele fallar al iniciar
Comando de instalación	`npm install -g @qwen-code/qwen-code@latest`
Verificar	`qwen --version`, luego `qwen` para abrir la UI interactiva
Primera ejecución	Usa `/auth` dentro de la UI para elegir tu proveedor

Si aparece qwen: command not found después de instalar, tu directorio global de binarios de npm no está en tu PATH: ejecuta npm config get prefix y añade su /bin a PATH. En Linux, un error de permisos durante la instalación global suele significar que necesitas sudo o, mejor, un Node gestionado por nvm para que las instalaciones globales no toquen directorios del sistema.

¿Cómo configuro Qwen CLI ahora que el nivel gratuito desapareció?

Configuras Qwen Code con una clave de API compatible con OpenAI, porque el nivel gratuito de Qwen OAuth se [discontinuó el 2026-04-15](https://github.com/QwenLM/qwen-code/issues/3203): los tokens en caché pueden persistir un tiempo, pero los nuevos inicios de sesión se rechazan. Ese nivel gratuito solía dar 2,000 solicitudes al día y 60 por minuto; muchos tutoriales de "usar Qwen Code gratis" todavía lo describen, y ahora están equivocados.

La configuración actual son tres variables de entorno. Defínelas, ejecuta qwen y elige "OpenAI" en el menú de autenticación:

export OPENAI_API_KEY="your_api_key"
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export OPENAI_MODEL="qwen3-coder-plus"
qwen

¿Prefieres un archivo de configuración? Qwen Code lee ~/.qwen/settings.json (o un .qwen/settings.json local del proyecto), donde defines un proveedor de modelos una vez:

{
  "modelProviders": {
    "openai": {
      "protocol": "openai",
      "models": [{
        "id": "qwen3-coder-plus",
        "envKey": "DASHSCOPE_API_KEY",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }]
    }
  },
  "security": { "auth": { "selectedType": "openai" } }
}

Tus opciones de proveedor hoy son ModelStudio Coding Plan de Alibaba Cloud (una suscripción mensual fija), la API de pago por token de DashScope, OpenRouter, Fireworks o cualquier otro endpoint compatible con OpenAI. La documentación oficial de autenticación enumera el conjunto actual: consúltala en lugar de un blog antiguo, ya que esta es exactamente la parte que quedó desactualizada.

¿Cómo ejecuto Qwen CLI con cualquier modelo a través de un solo endpoint?

Apunta OPENAI_BASE_URL a una gateway y una sola clave ejecuta Qwen Code contra muchos modelos, sin tener que manejar cuentas por proveedor. Como Qwen Code solo necesita un endpoint compatible con OpenAI, Velokey funciona como reemplazo directo: una clave llega a Qwen, GPT, Claude y GLM a través de la misma URL base.

Qwen Code CLI conectándose a través de un endpoint compatible con OpenAI a modelos Qwen, GPT, Claude y GLM

export OPENAI_API_KEY="sk-your-velokey-key"
export OPENAI_BASE_URL="https://api.velokey.ai/v1"
export OPENAI_MODEL="qwen3.7-max"
qwen

La ventaja práctica es cambiar backends sin volver a autenticarse. Qwen Code está ajustado para modelos Qwen, así que [qwen3.7-max](/model/qwen3.7-max) es el valor predeterminado natural; pero si una tarea requiere un modelo diferente, cambia una variable:

Establece `OPENAI_MODEL` en	Cuándo
`qwen3.7-max`	Predeterminado: Qwen Code está ajustado para modelos Qwen
`gpt-5.6`	Quieres el razonamiento de GPT-5.6 en una refactorización difícil
`claude-sonnet-5`	Prefieres el estilo de programación de Claude
`glm-5.2`	Ejecuciones de programación sensibles al coste

Como la facturación es por token mediante créditos, no hay una suscripción separada ni un límite diario de solicitudes: pagas por lo que el agente realmente usa. Para ver cómo funcionan esos cálculos, consulta nuestra guía de precios de Claude API; el mismo modelo por token se aplica a Qwen y al resto.

¿Por qué Qwen CLI no funciona? Errores comunes

La mayoría de los fallos de Qwen CLI son problemas de entorno o autenticación, no bugs, y se agrupan en unas pocas causas. Inicia qwen --safe-mode para desactivar tus personalizaciones; si el problema desaparece, vuelve a habilitar la configuración de una en una para encontrar al culpable.

Síntoma	Causa	Solución
`qwen: command not found`	Binario global de npm no está en `PATH`	Añade `$(npm config get prefix)/bin` a `PATH`
No inicia / se bloquea al arrancar	Node.js < 22	Actualiza Node a 22+ (usa nvm)
Autenticación rechazada / 401	Nivel gratuito de OAuth discontinuado, o clave incorrecta	Configura una clave compatible con OpenAI + URL base
`EADDRINUSE` al iniciar	El puerto de un servidor MCP está ocupado	Libera el puerto o cambia la configuración de MCP
`MODULE_NOT_FOUND`	Instalación / dependencias rotas	Reinstala: `npm install -g @qwen-code/qwen-code@latest`
Errores de modelo en modelos que no son Qwen	Desajuste en el formato de llamadas a herramientas	Cambia `OPENAI_MODEL` a un modelo Qwen, o a un modelo sólido en uso de herramientas

Si tu clave está almacenada en una herramienta basada en navegador en lugar de una variable de entorno, una sesión faltante puede lanzar otra clase de error: consulta nuestra guía sobre cómo solucionar "API key not found in cookies". Para un recorrido completo de extremo a extremo sobre cómo conectar una clave de API a un cliente, cómo llamar a un modelo con una clave de API cubre el patrón de configuración.

Preguntas frecuentes

¿Cómo instalo Qwen CLI?

Ejecuta npm install -g @qwen-code/qwen-code@latest en Node.js 22 o posterior, luego qwen --version para confirmar. En macOS también puedes usar brew install qwen-code. Si aparece command not found, añade tu directorio global de binarios de npm (npm config get prefix + /bin) a tu PATH.

¿Qwen CLI es gratis?

Ya no a través de la ruta integrada: el nivel gratuito de Qwen OAuth se discontinuó el 2026-04-15. El CLI en sí es open-source y gratuito, pero ahora necesitas un proveedor de API: ModelStudio Coding Plan de Alibaba, DashScope de pago por token, OpenRouter o cualquier endpoint compatible con OpenAI configurado con tu propia clave.

¿Cómo uso Qwen CLI con mi propia clave de API?

Define tres variables de entorno — OPENAI_API_KEY, OPENAI_BASE_URL y OPENAI_MODEL — luego ejecuta qwen y selecciona "OpenAI" en el menú de autenticación. También puedes definir un proveedor en ~/.qwen/settings.json. La URL base apunta al proveedor compatible con OpenAI que estés usando.

¿Qué modelos admite Qwen Code CLI?

Qwen Code está ajustado para modelos Qwen como Qwen3-Coder, pero como habla el protocolo compatible con OpenAI, se ejecuta contra OpenAI, Anthropic, Gemini, OpenRouter, modelos locales vía Ollama o vLLM, y gateways. Establece OPENAI_MODEL al ID de modelo que expone tu proveedor.

¿Por qué Qwen CLI dice "command not found"?

Tu directorio global de binarios de npm no está en tu PATH. Ejecuta npm config get prefix para encontrar el prefijo de instalación, luego añade su subcarpeta /bin a tu PATH y reinicia tu shell. Este es el error más común posterior a la instalación y no tiene nada que ver con la herramienta en sí.

¿Puedo ejecutar Qwen CLI contra una gateway en lugar de la API de Qwen?

Sí. Qwen Code acepta cualquier endpoint compatible con OpenAI, así que puedes apuntar OPENAI_BASE_URL a una gateway y acceder a múltiples modelos con una sola clave. Establece OPENAI_MODEL al modelo que quieras: un modelo Qwen para la mejor fidelidad en llamadas a herramientas, u otro modelo según la tarea.