Qwen Code: guía práctica del agente de IA en la terminal

Qwen Code es el agente de IA de código abierto de Alibaba que vive en la terminal: lo ejecutas dentro de tu repo con qwen, le describes una tarea en lenguaje natural y él lee archivos, corre comandos, edita y muestra cambios como diff. Nació como un fork de Gemini CLI v0.8.2, se separó del upstream en v0.1 y hoy es una plataforma independiente multi-proveedor: sirve con modelos Qwen, pero también con OpenAI, Anthropic, Gemini, DeepSeek, Kimi, MiniMax y un servidor local.

Esta guía cubre el flujo completo de la serie de agentes CLI del hub Construir agentes: instalación, autenticación, configuración sin login interactivo, modo headless para CI y cuándo elegirlo frente a Gemini CLI o OpenCode. Complementa AGENTS.md para coding agents (las reglas que le pasas) y worktrees para coding agents (dónde correrlo sin pisar tu trabajo).

Instalación: tres caminos

La documentación oficial ofrece un instalador que usa un binario standalone y solo cae a npm si tu plataforma no tiene archivo propio:

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

En Windows el equivalente es irm <misma-url>.ps1 | iex. Si prefieres gestionarlo con tu manejador de paquetes:

npm install -g @qwen-code/qwen-code@latest   # requiere Node.js 22+
brew install qwen-code                       # macOS / Linux

Tras instalar, reinicia la terminal si qwen no aparece en PATH. Verifica con qwen --version y entra en tu proyecto antes de lanzarlo: cd tu-repo && qwen. En el primer arranque te pide conectar un proveedor de modelo; eso es lo que resolvemos en la siguiente sección.

Autenticación: el menú /auth de 2026

Ejecuta qwen, escribe /auth y verás tres opciones de primer nivel en la guía de autenticación:

Opción	Cuándo usarla	Cómo conecta
Alibaba ModelStudio	Uso normal con Qwen: coste predecible	Submenú con Coding Plan (fijo mensual), Token Plan (billing por uso) o Standard API Key
Third-party Providers	Ya tienes key de otro proveedor	DeepSeek, Grok, MiniMax, Z.AI, Kimi, Idealab, ModelScope, OpenRouter, Requesty
Custom Provider	Servidor local, proxy o provider no listado	Endpoints compatibles OpenAI, Anthropic, Gemini

Un dato clave para 2026: el OAuth gratuito de Qwen está discontinuado desde el 2026-04-15. Ya no aparece como entrada seleccionable en /auth y los tokens cacheados viejos dejan de funcionar. No intentes un login tipo "cuenta qwen.ai": ve directo a ModelStudio o a un provider tercero.

La vía recomendada para individuos es Alibaba Cloud Coding Plan: suscripción mensual fija, endpoint dedicado https://coding.dashscope.aliyuncs.com/v1 (China) o https://coding-intl.dashscope.aliyuncs.com/v1 (internacional), y acceso a modelos Qwen (qwen3-coder-plus, qwen3.7-plus…) más terceros como GLM, Kimi o MiniMax desde /model.

Configurar sin login interactivo: ~/.qwen/settings.json

Para CI, contenedores o sesiones SSH (donde el flujo interactivo de /auth no funciona), configura todo en ~/.qwen/settings.json. Ejemplo completo de la doc oficial conectando Qwen3-Coder vía DashScope:

{
  "modelProviders": {
    "openai": [{
      "id": "qwen3-coder-plus",
      "name": "qwen3-coder-plus (Coding Plan)",
      "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
      "envKey": "BAILIAN_CODING_PLAN_API_KEY"
    }]
  },
  "env": { "BAILIAN_CODING_PLAN_API_KEY": "tu-key-aqui" },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "qwen3-coder-plus" }
}

Los campos importantes: modelProviders declara modelos y protocolo (las claves openai, anthropic, gemini, vertex-ai), security.auth.selectedType fija el protocolo al arrancar sin /auth, y model.name activa el modelo por defecto. La API key en env tiene la prioridad más baja: si exportas la variable en shell o en un .env, eso gana. Prefiere definir modelProviders en scope de usuario y usa envKey en lugar de guardar la llave dentro del archivo.

Para headless puro con el Coding Plan, la versión mínima es de tres variables:

export BAILIAN_CODING_PLAN_API_KEY="tu-key"
export OPENAI_BASE_URL="https://coding-intl.dashscope.aliyuncs.com/v1"
export OPENAI_MODEL="qwen3-coder-plus"

Modos: interactivo, headless, daemon y canales

Qwen Code tiene cuatro formas de ejecutarse (tabla de la tabla de modos del README):

Modo	Comando	Para qué
Interactivo	qwen	TUI con @archivo para referenciar contexto y slash commands
Headless	qwen -p "tarea"	Scripts, CI, procesamiento por lotes, sin UI
Daemon	qwen serve	Sesión compartida por HTTP+SSE (ACP), varios clientes, un agente
IM Bot	qwen channel	Conectar a Telegram, DingTalk, WeChat o Feishu

El modo headless es el más útil para automatización: cumple la filosofía Unix y se compone con pipes. La doc oficial muestra tail -f app.log | qwen -p "Slack me if you see any anomalies appear in this log stream" y un CI que corre qwen -p "traduce estas cadenas y abre un PR". Para scripts ten en cuenta que la autenticación debe estar resuelta antes (el bloque de settings.json o las variables del apartado anterior), porque no hay navegador para login.

¿Qwen Code o Gemini CLI?

Comparten ADN: Qwen Code arrancó desde Gemini CLI v0.8.2. La decisión práctica en 2026:

Criterio	Qwen Code	Gemini CLI
Modelo por defecto	Qwen (open-source) + terceros	Gemini (Google)
Proveedores	OpenAI, Anthropic, Gemini, DeepSeek, Kimi, MiniMax, local…	Google + providers compatibles
Coste	Coding Plan fijo o API key	Pago por uso de Gemini API
Código	Framework y modelos open-source	CLI open-source, modelos cerrados
Extra	Daemon ACP, SDK (TS/Python/Java), bots de Telegram/WeChat, Agent Arena	Ecosistema Google, integración Workspace

Elige Qwen Code si quieres un solo agente que hable con varios proveedores (especialmente los económicos para LATAM como DeepSeek o Kimi), prefieres modelo abierto, o necesitas daemon/bots/SDK. Elige Gemini CLI si tu flujo ya vive en Google (corporativo, Workspace) o quieres el modelo insignia de Google sin salir de su ecosistema.

Checklist para usarlo sin romper tu repo

• Corre qwen dentro del repo, no desde cualquier carpeta.
• Resuelve /auth antes de la primera tarea; en CI usa settings.json o variables.
• Guarda las API keys fuera del repo: variables de entorno o .env ignorado por git.
• Revisa el diff de cada cambio antes de aceptarlo; el agente edita archivos reales.
• Para cambios experimentales usa una rama o worktree.
• Define reglas de proyecto en AGENTS.md.
• En headless, prueba primero con -p una tarea pequeña antes de lanzar el pipeline completo.

FAQ

¿Qwen Code es gratis? El framework y los modelos Qwen son open-source, pero los modelos se sirven desde tu proveedor: Coding Plan (fijo mensual), Token Plan o API key. El tier OAuth gratuito murió el 2026-04-15.

¿Puedo usar mis propias keys de OpenAI o Anthropic? Sí: modelProviders acepta protocolos openai y anthropic, y el menú /auth incluye providers terceros.

¿Funciona offline con Ollama o vLLM? Sí, con un Custom Provider apuntando a tu servidor local compatible con la API de OpenAI.

¿Sustituye a Claude Code o Codex? Para flujos de terminal, rivaliza en capacidades (SubAgents, MCP, Plan Mode, sandbox). La ventaja diferencial de Qwen Code es el modelo abierto y la multi-protocol.