Cómo usar Qwen Code: guía paso a paso

Para usar Qwen Code, instala la CLI qwen con el script oficial, npm o Homebrew, ejecuta qwen en la carpeta de un proyecto, elige un proveedor de modelos con /auth y describe lo que quieres. Qwen Code lee tu código, edita archivos y ejecuta comandos, y te pide permiso según el modo de aprobación que elijas. Como el plan gratuito de Qwen OAuth terminó el 15 de abril de 2026, necesitas una API key o un plan de algún proveedor, o un modelo local.

Ese es el ciclo básico. Esta guía cubre el resto: las opciones de inicio de sesión y qué sustituyó al plan gratuito, las claves compatibles con OpenAI y los modelos locales, la elección del modelo, los modos de aprobación, QWEN.md, los servidores MCP, el modo headless para scripts y cómo usar Qwen Code junto a otros agentes. Todo sigue el repositorio y la documentación oficiales de Qwen Code a octubre de 2026.

Qué es Qwen Code

Qwen Code es un agente de programación para la terminal creado por el equipo de Qwen en Alibaba y publicado bajo la licencia Apache-2.0. Nació a partir de Gemini CLI, así que su estructura te resultará familiar si has usado el agente de Google, aunque hace tiempo que se desarrolla por su cuenta. Está ajustado para los modelos de programación de Qwen, pero no depende de ellos: habla los formatos de API de OpenAI, Anthropic y Gemini y funciona con modelos locales.

Además de la terminal, el proyecto ofrece una app de escritorio, integraciones para VS Code, Zed y JetBrains, y SDK para TypeScript, Python y Java. Esta guía se centra en la CLI.

Paso 1: instala Qwen Code

Después de instalar con el script, reinicia la terminal para que el comando qwen esté en tu PATH. El paquete de npm necesita Node.js 22 o posterior. Para actualizar, vuelve a ejecutar el mismo comando de npm o Homebrew.

Paso 2: inicia sesión con /auth

Entra en un proyecto y arranca Qwen Code:

cd my-project
qwen

En el primer arranque, y cuando quieras después con /auth, Qwen Code muestra cuatro formas de conectar un modelo:

Ejecuta /doctor dentro de una sesión para ver qué autenticación está activa. El antiguo comando de shell qwen auth se eliminó, así que para cambiar de proveedor se usa /auth.

Qué pasó con el plan gratuito de Qwen OAuth

Durante mucho tiempo, lo más fácil era iniciar sesión con una cuenta de qwen.ai mediante Qwen OAuth y recibir una cuota diaria gratuita. La documentación dice ahora que el plan gratuito de Qwen OAuth se retiró el 15 de abril de 2026. Ya no aparece en /auth y las nuevas solicitudes por esa vía se rechazan aunque quede un token antiguo en caché. Si seguiste un tutorial viejo y el agente dejó de responder de repente, este es el motivo. Elige una de las opciones de arriba. Nuestra selección de mejores herramientas de IA gratuitas para programar repasa lo que sigue sin costar nada en 2026.

Usa cualquier API key compatible con OpenAI

La configuración más rápida para scripts y servidores son tres variables de entorno:

export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_MODEL="your-model-id"
qwen

Son las variables del protocolo compatible con OpenAI, que cubre a la mayoría de los proveedores. Los formatos de Anthropic y Gemini tienen las suyas (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_MODEL y GEMINI_API_KEY, GEMINI_MODEL).

En lugar de exportar las claves en cada shell, puedes guardarlas en un archivo .env. Qwen Code busca .qwen/.env y .env en el proyecto y sus carpetas superiores, luego ~/.qwen/.env y ~/.env, y solo carga el primero que encuentra. Las flags de la línea de comandos mandan sobre las variables del shell, estas sobre .env, y .env sobre el bloque env de settings.json.

Para una configuración permanente, declara el proveedor en ~/.qwen/settings.json. envKey indica la variable que contiene la clave:

{
  "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"
      }
    ]
  },
  "security": { "auth": { "selectedType": "openai" } },
  "model": { "name": "qwen3-coder-plus" }
}

El archivo también acepta un bloque env con la clave misma, pero así queda guardada en texto plano. La documentación recomienda .qwen/.env para los secretos del proyecto, fuera de Git.

Modelos locales con Ollama

Ollama, vLLM y LM Studio exponen una API compatible con OpenAI, así que un modelo local es un proveedor openai más con una baseUrl local. Ollama no necesita una clave real; basta con cualquier marcador:

{
  "env": { "OLLAMA_API_KEY": "ollama" },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen2.5-7b",
        "name": "Qwen2.5 7B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": { "contextWindowSize": 32768 }
      }
    ]
  }
}

El id debe coincidir con el nombre del modelo en Ollama. Un modelo local pequeño sufre en sesiones largas de agente; nuestra guía sobre un agente de programación con un LLM local explica qué modelos y cuánta memoria lo hacen viable.

Paso 3: elige un modelo

Dentro de una sesión, /model abre un selector con los modelos de tus proveedores y /model <model-id> cambia directamente. Desde el shell, qwen --model qwen3-coder-plus (o -m) fija el modelo para una ejecución. En los modelos con razonamiento, /effort ajusta el nivel de razonamiento si el proveedor lo admite.

Los modelos disponibles dependen del proveedor. A octubre de 2026, el Coding Plan de Alibaba incluye modelos de Qwen como qwen3-coder-plus, qwen3-coder-next y qwen3.7-plus, además de modelos de terceros como GLM, Kimi y MiniMax. Una clave de pago por uso te da lo que ofrezca la API de ese proveedor.

Paso 4: lo básico de una sesión

La pantalla de Qwen Code es un chat con tu proyecto. Algunas cosas que usarás todo el tiempo:

• @ruta añade un archivo a tu mensaje y @carpeta/ lee los archivos de texto de una carpeta.
• !comando ejecuta un comando de shell, por ejemplo !git status. Un ! solo cambia al modo shell hasta que vuelvas a escribir !.
• Shift+Tab (Tab en Windows) recorre los modos de aprobación.

Desde el shell, qwen --continue reabre la última sesión del proyecto actual y qwen --resume <id> abre una concreta.

Paso 5: modos de aprobación

Qwen Code tiene cinco modos de aprobación que deciden qué puede hacer sin preguntar:

De serie, Qwen Code arranca en Auto: un clasificador basado en un modelo aprueba las acciones seguras y bloquea las arriesgadas. Usa /approval-mode plan o Shift+Tab para cambiar, o arranca con qwen --approval-mode plan. Un buen hábito para cualquier cosa no trivial: empieza en Plan, acordad un enfoque y luego pasa a Auto-Edit o Auto para ejecutarlo. Reserva YOLO para contenedores o máquinas desechables, donde un comando equivocado no pueda causar daños duraderos.

Paso 6: QWEN.md y el contexto del proyecto

QWEN.md es el briefing que Qwen Code carga al inicio de cada sesión: comandos de build y tests, convenciones, carpetas que no debe tocar. Puede estar en tres sitios y se cargan todos:

Ejecuta /init y Qwen Code analiza el proyecto y escribe un QWEN.md inicial; si ya existe, propone añadidos en lugar de sobrescribirlo. Si el repositorio ya tiene un AGENTS.md para otras herramientas, Qwen Code también lo lee. Dentro de QWEN.md, @docs/git-workflow.md incorpora otro archivo.

# Reglas del proyecto

- Gestor de paquetes: pnpm. Ejecuta `pnpm test` antes de terminar una tarea.
- TypeScript en modo estricto; nada de `any` en código nuevo.
- No edites nunca archivos en src/generated/.
- Flujo de Git: @docs/git-workflow.md

Mantenlo corto; la documentación advierte que un archivo largo se sigue con menos fiabilidad. Qwen Code también guarda su propia memoria automática en ~/.qwen/projects/<proyecto>/memory/, archivos Markdown que puedes editar o desactivar en /memory. Para reglas que solo afectan a ciertos archivos, .qwen/rules/ admite archivos Markdown con un campo paths:. Qué poner en un archivo así lo explica CLAUDE.md y AGENTS.md, y vale igual para QWEN.md.

Paso 7: servidores MCP

Los servidores MCP dan a Qwen Code herramientas nuevas, como un navegador, un gestor de incidencias o la búsqueda en documentación. La forma más rápida de añadir uno es el comando qwen mcp:

# un servidor remoto por HTTP
qwen mcp add --transport http my-server http://localhost:3000/mcp

# un servidor local que arranca como proceso (stdio es el transporte por defecto)
qwen mcp add pythonTools -e DATABASE_URL=$DB_CONNECTION_STRING python -m my_mcp_server

# quitarlo de nuevo
qwen mcp remove my-server

Los servidores se guardan en el bloque mcpServers de ~/.qwen/settings.json (el ámbito de usuario por defecto) o, con --scope project, en .qwen/settings.json. También puedes editar ese bloque a mano: command y args para un proceso local, httpUrl para un servidor HTTP. --include-tools y --exclude-tools limitan qué herramientas expone un servidor. Si Qwen Code ya estaba abierto, reinícialo y escribe /mcp para comprobar que el servidor se conectó y ver sus herramientas.

Paso 8: modo headless para scripts y CI

-p (o --prompt) ejecuta una sola tarea sin la interfaz interactiva, y stdin también funciona:

qwen -p "Summarize what changed in src/ since the last tag"
cat error.log | qwen -p "Explain this stack trace"
qwen -p "List the TODOs in this repo" --output-format json > todos.json

--output-format acepta text, json o stream-json. qwen --continue -p "..." continúa la última sesión, de modo que un script puede trabajar en varios pasos. Para que una ejecución headless pueda editar archivos, fija un modo de aprobación como --approval-mode auto-edit, o --yolo en un runner aislado. La documentación es clara: --yolo no activa ningún sandbox y los comandos de shell se ejecutan con los permisos de tu usuario. Los límites evitan que una ejecución desatendida se descontrole:

qwen -p "Fix the failing unit tests" --yolo \
  --max-session-turns 30 --max-wall-time 10m --output-format json

Una ejecución que supera --max-wall-time o --max-tool-calls termina con el código 55, y una que supera --max-session-turns, con el 53, así que CI puede distinguir los casos. Para un aislamiento real, qwen -s ejecuta las herramientas en un sandbox (Seatbelt en macOS, Docker o Podman en los demás sistemas).

Errores habituales

• El agente dejó de funcionar después de abril de 2026. Usabas el plan gratuito de Qwen OAuth, que ya no existe. Ejecuta /auth y elige otro proveedor.
• “qwen auth” muestra un aviso de que se eliminó. El comando ya no existe; usa /auth en una sesión y /doctor para comprobar.
• Se ignora una clave en QWENCLOUD_API_KEY o DASHSCOPE_API_KEY. Las variables específicas de un proveedor solo funcionan cuando un proveedor de settings.json las indica como envKey. Si no, usa OPENAI_API_KEY.
• Un servidor MCP nuevo no aparece. Se añadió con Qwen Code abierto. Reinícialo en el mismo proyecto.
• Las sesiones largas se vuelven lentas y caras. Usa /compress o /clear, mantén QWEN.md corto y desactiva los servidores MCP que no necesites.

Ejecutar Qwen Code junto a otras CLI

Qwen Code tiene sus propios subagentes y soporte para worktrees, pero se quedan dentro de Qwen Code. Si quieres Qwen Code en una tarea, Claude Code en otra y Gemini CLI en una tercera, vuelves a hacer malabares con pestañas de terminal. AgentVera es una app de escritorio que ejecuta estas CLI en paralelo en terminales reales, con tus propias instalaciones e inicios de sesión. Su soporte para Qwen Code funciona así:

• Tu inicio de sesión. Qwen Code mantiene su propio inicio de sesión y la terminal del agente lo pide en el primer arranque. Si qwen no está instalado, AgentVera lo instala con npm i -g @qwen-code/qwen-code.
• Una sesión por agente. Cada agente arranca con su propio identificador de sesión (--session-id) y una sesión guardada se reabre con --resume.
• Rol y modelo. El rol del agente se añade al prompt de sistema de Qwen Code con --append-system-prompt. Deja vacío el campo Model para usar el modelo por defecto de Qwen Code, o elige uno y AgentVera lo pasa con --model.
• MCP en cada arranque. Los servidores del gestor de MCP de AgentVera y el navegador de AgentVera se pasan con --mcp-config, así que tu settings.json queda como está.
• Paneles, revisión y flows. Ejecuta Qwen Code junto a Claude Code en la cuadrícula del Workspace, cada agente en su propio worktree de git, con revisión de código automática al terminar cada turno. Los agentes de Qwen Code también funcionan en difusiones, tareas programadas y Flows (Pro y Team), donde la respuesta de un agente pasa al siguiente.
• Varias cuentas. En Settings → Accounts → Accounts of other agents puedes añadir cuentas extra de Qwen, que funcionan con API keys, y fijar un orden de respaldo (Pro y Team).

Para ser justos con las alternativas: si solo quieres un modelo alojado gratuito, Qwen Code ya no lo ofrece, y las herramientas gratuitas de la selección enlazada arriba son un mejor punto de partida. Si buscas un agente independiente del proveedor con otro flujo de trabajo, opencode es la alternativa más cercana. La cuadrícula, los worktrees, la revisión de código y el gestor de MCP están en el plan gratuito. Descarga AgentVera para probarlo.

Conclusión

Para usar Qwen Code, instálalo, ejecuta qwen en un proyecto y elige un proveedor con /auth, ya que el plan gratuito de Qwen OAuth desapareció. Cualquier clave compatible con OpenAI funciona con las variables OPENAI_* o con settings.json, modelos locales incluidos. Empieza el trabajo arriesgado en modo Plan, pon las reglas del proyecto en QWEN.md, añade herramientas con qwen mcp add y usa qwen -p con límites cuando un script o un job de CI necesite al agente. A partir de ahí, la decisión principal es qué proveedor y qué modelo encajan con tu presupuesto, y Qwen Code te deja cambiar ambos cuando quieras.