Objetivo del tema
Comprender cómo se autentica Qwen Code, qué métodos oficiales existen, cuándo conviene usar cada uno y cómo dejar el entorno listo para trabajar con seguridad tanto en sesiones interactivas como en automatizaciones.
Este tema se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en la sección de autenticación de Qwen Code Docs, la guía de Quickstart y la documentación de Model Providers.
Qwen Code no es solamente un ejecutable local. Para poder acceder a modelos y ejecutar sesiones reales, necesita saber con qué cuenta o con qué proveedor va a trabajar. Por eso la autenticación no es un detalle secundario del arranque: es la pieza que conecta el CLI con el servicio o con el proveedor de modelos elegido.
En la práctica, autenticar Qwen Code significa resolver tres preguntas:
Una instalación correcta no alcanza si la autenticación queda mal resuelta. El CLI puede estar bien instalado y aun así no ser usable hasta que el método de acceso quede definido correctamente.
La documentación oficial actual indica que Qwen Code soporta tres métodos principales de autenticación:
qwen.ai.| Método | Cuándo conviene | Característica principal |
|---|---|---|
| Qwen OAuth | Cuando se quiere la configuración más simple y se va a trabajar con la experiencia oficial de Qwen. | No requiere administrar API keys manualmente. |
| Alibaba Cloud Coding Plan | Cuando se necesita una cuota mayor, costos previsibles y acceso a modelos soportados por el plan. | Usa endpoint dedicado y clave de suscripción. |
| API Key | Cuando se necesita flexibilidad para usar otros proveedores o entornos no interactivos. | Se apoya en variables de entorno, `.env` o `settings.json`. |
La documentación presenta Qwen OAuth como la opción recomendada para empezar cuando se trabaja con Qwen Code en forma interactiva y se desea la menor fricción posible.
El flujo general es este:
qwen.qwen.ai.qwen
También puede lanzarse el flujo de autenticación directamente desde terminal sin abrir primero una sesión completa:
qwen auth qwen-oauth
Según la documentación oficial, las credenciales quedan almacenadas localmente para evitar repetir el login en cada arranque. Además, Qwen OAuth ofrece una experiencia gratuita con cuota diaria.
Al 11 de abril de 2026, la guía oficial de autenticación indica para Qwen OAuth una cuota de:
Eso lo vuelve especialmente útil para aprendizaje, uso individual y primeras pruebas del CLI.
Aunque Qwen OAuth es la vía más sencilla, no siempre es la más adecuada. La propia documentación advierte que en entornos no interactivos o headless normalmente no se puede completar cómodamente el flujo del navegador.
En este contexto, headless significa que el entorno no dispone de una interfaz gráfica o de un navegador accesible para completar el inicio de sesión visual. Es decir, Qwen Code puede ejecutarse, pero no hay una pantalla interactiva convencional donde abrir la página de autenticación, iniciar sesión y volver al CLI con normalidad.
Un entorno headless suele tener estas características:
Por eso, cuando la documentación dice que OAuth no siempre conviene en modo headless, lo que realmente está señalando es que el flujo basado en navegador deja de ser cómodo o directamente deja de ser viable. En esas situaciones resulta más razonable trabajar con API Key o con Alibaba Cloud Coding Plan.
Ejemplos típicos:
En esos casos, la recomendación oficial es usar Alibaba Cloud Coding Plan o API Key.
El segundo método oficial es Alibaba Cloud Coding Plan. Está orientado a quienes quieren costos más previsibles, cuotas más altas y una selección amplia de modelos soportados por el plan.
La documentación explica que este método funciona mediante:
Hay dos formas principales de configurarlo.
Opción A: desde la terminal
qwen auth coding-plan
# o en modo no interactivo
qwen auth coding-plan --region china --key sk-sp-xxxxxxxxx
Opción B: dentro de una sesión de Qwen Code
qwen
# dentro de la sesión
/auth
Después de elegir Alibaba Cloud Coding Plan, la herramienta pide región y clave. Luego se pueden seleccionar modelos soportados mediante el comando /model.
La documentación actual menciona dos regiones para este plan:
https://coding.dashscope.aliyuncs.com/v1https://coding-intl.dashscope.aliyuncs.com/v1Cuando Coding Plan se configura mediante el flujo asistido de /auth, la documentación indica que la clave se guarda usando la variable reservada BAILIAN_CODING_PLAN_API_KEY. Por defecto, puede terminar almacenada dentro del campo env de settings.json.
Sin embargo, la propia documentación recomienda una práctica más segura: mover la clave a un archivo .env, por ejemplo:
# ~/.qwen/.env
BAILIAN_CODING_PLAN_API_KEY=tu-api-key-aqui
Ese enfoque reduce el riesgo de dejar secretos mezclados con configuraciones generales.
El tercer método oficial es API Key. En este caso, Qwen Code no depende de Qwen OAuth, sino que se conecta a proveedores compatibles usando claves y configuración explícita.
La documentación destaca esta opción para trabajar con:
La forma recomendada por la documentación actual es definir todo en ~/.qwen/settings.json. Ejemplo simplificado:
{
"modelProviders": {
"openai": [
{
"id": "qwen3-coder-plus",
"name": "qwen3-coder-plus",
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"description": "Qwen3-Coder via Dashscope",
"envKey": "DASHSCOPE_API_KEY"
}
]
},
"env": {
"DASHSCOPE_API_KEY": "sk-xxxxxxxxxxxxx"
},
"security": {
"auth": {
"selectedType": "openai"
}
},
"model": {
"name": "qwen3-coder-plus"
}
}El sentido de esta configuración es muy importante:
modelProviders declara qué modelos y protocolos están disponibles.envKey indica qué variable de entorno contiene la credencial.selectedType define qué protocolo de autenticación usar al iniciar.model.name define el modelo predeterminado.La documentación de autenticación explica que Qwen Code puede leer variables de entorno desde archivos .env y que recomienda usar .qwen/.env para mantener aisladas las variables propias del CLI.
También describe un orden de búsqueda. Qwen Code intenta encontrar el primer archivo válido en esta secuencia:
.qwen/.env desde el directorio actual hacia arriba.env desde el directorio actual hacia arriba~/.qwen/.env~/.envLa búsqueda se detiene en el primer archivo encontrado. Eso significa que las variables no se fusionan desde múltiples archivos; prevalece el primero que aparece en ese recorrido.
Este detalle es clave para evitar confusiones. Si el usuario cree que Qwen Code está leyendo varias fuentes al mismo tiempo, puede diagnosticar mal un problema de autenticación.
En el trabajo diario conviene reconocer cuatro comandos esenciales:
qwen
qwen auth
qwen auth status
/auth
| Comando | Uso | Escenario típico |
|---|---|---|
qwen |
Inicia una sesión interactiva y puede disparar el login inicial. | Primer uso o trabajo diario dentro de un proyecto. |
qwen auth |
Configura autenticación desde terminal sin abrir una sesión completa. | Preparación del entorno o cambio de método. |
qwen auth status |
Muestra el estado actual de autenticación. | Diagnóstico rápido. |
/auth |
Permite cambiar el método dentro de la sesión del CLI. | Cuando ya estás trabajando y necesitás reconfigurar credenciales. |
La guía de Quickstart indica que, al autenticar Qwen Code con una cuenta Qwen, se crea automáticamente un workspace llamado .qwen. Ese espacio cumple un rol importante en la experiencia del producto, porque centraliza datos de configuración y administración del uso.
En el curso conviene asociar .qwen con varias funciones:
Más adelante estudiaremos con mayor detalle settings.json, pero ya desde este tema conviene fijar la idea de que .qwen es una pieza estructural del ecosistema de Qwen Code.
Autenticarse no solo consiste en hacer que el CLI funcione. También hay que hacerlo de forma segura. La documentación deja pistas claras sobre qué conviene hacer y qué conviene evitar.
Estas decisiones reducen errores comunes y evitan exponer credenciales en lugares incorrectos.
En la práctica, la autenticación puede fallar por varios motivos repetidos. Reconocerlos permite diagnosticar más rápido:
| Problema | Causa probable | Primer paso razonable |
|---|---|---|
| El login OAuth no se completa | Entorno sin navegador o sin conectividad adecuada. | Probar qwen auth desde un entorno interactivo normal o cambiar a API Key. |
qwen inicia, pero no accede al modelo |
Autenticación incompleta o proveedor mal configurado. | Revisar qwen auth status y la configuración activa. |
| API key aparentemente válida, pero sin efecto | Variable mal nombrada, archivo `.env` no detectado o `selectedType` incorrecto. | Revisar el nombre de `envKey`, el orden de búsqueda y el auth type seleccionado. |
| Modelo no disponible en `/model` | El proveedor o modelo no fue declarado correctamente en `modelProviders`. | Corregir `settings.json` y volver a abrir Qwen Code. |
La elección depende del contexto de uso:
Una forma simple de recordarlo es esta: OAuth para simplicidad, Coding Plan para escala controlada, API Key para flexibilidad.
Qwen Code admite tres rutas principales de autenticación y cada una responde a una necesidad distinta. Lo importante no es memorizar comandos sueltos, sino entender el criterio detrás de cada método.
En este tema vimos las ideas centrales:
qwen auth, qwen auth status y /auth son comandos clave del flujo diario.Con esta base, el siguiente paso natural es estudiar la configuración de Qwen Code: cómo se organiza settings.json, qué opciones conviene definir y cómo personalizar el comportamiento del agente.