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

URL: https://agentvera.dev/es/blog/how-to-use-qwen-code/ · Publicado: 2026-10-29

Cómo usar Qwen Code: instala la CLI qwen, inicia sesión con /auth o una API key, elige un modelo y configura QWEN.md, servidores MCP y el modo headless.

**En resumen:**

- Instala Qwen Code con el script oficial, npm (Node.js 22+) o Homebrew, ejecuta qwen en un proyecto y elige un proveedor con /auth. El plan gratuito de Qwen OAuth terminó el 15 de abril de 2026.
- Sirve cualquier clave compatible con OpenAI: define OPENAI_API_KEY, OPENAI_BASE_URL y OPENAI_MODEL, o declara proveedores en ~/.qwen/settings.json. Los modelos locales con Ollama funcionan igual.
- Las reglas del proyecto van en QWEN.md (también lee AGENTS.md), los servidores MCP se añaden con qwen mcp add y qwen -p ejecuta una sola tarea sin interfaz para scripts y CI.

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

| Plataforma | Comando |
| --- | --- |
| macOS, Linux | `curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh \| bash` |
| Windows (PowerShell) | `irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.ps1 \| iex` |
| Cualquier plataforma con Node.js 22+ | `npm install -g @qwen-code/qwen-code@latest` |
| macOS, Linux (Homebrew) | `brew install 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:

```bash
cd my-project
qwen
```

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

| Opción | Qué es |
| --- | --- |
| QwenCloud | La API de Qwen de Alibaba: una suscripción Token Plan con una cuota mensual de créditos o una clave estándar de pago por uso. También activa la herramienta de búsqueda web integrada de Qwen Code. |
| Alibaba ModelStudio | Alibaba Cloud Model Studio: el Coding Plan para desarrolladores individuales (cuota mensual fija con un límite semanal), un Token Plan para equipos o una API key estándar |
| Third-party Providers | Entradas listas para DeepSeek, Grok, MiniMax, Z.AI, Kimi, ModelScope, OpenRouter, Requesty y otros |
| Custom Provider | Cualquier endpoint compatible con OpenAI, Anthropic o Gemini: un proxy, un gateway o un servidor local |

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](/es/blog/best-free-ai-coding-tools/ "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:

```bash
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:

```json
{
  "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:

```json
{
  "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](/es/blog/local-llm-coding-agent/ "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.

| Comando | Qué hace |
| --- | --- |
| `/auth` | Elegir o cambiar el proveedor |
| `/model` | Cambiar el modelo |
| `/init` | Crear un `QWEN.md` inicial para el proyecto |
| `/memory` | Abrir el gestor de memoria |
| `/mcp` | Listar los servidores MCP y sus herramientas |
| `/approval-mode` | Cambiar el modo de aprobación de esta sesión |
| `/compress` | Sustituir el historial por un resumen para liberar contexto |
| `/clear` | Borrar la conversación |
| `/resume` | Reabrir una sesión anterior |
| `/restore` | Revertir los archivos al punto de control anterior a una llamada a herramienta |
| `/stats` | Uso de tokens y coste estimado |
| `/doctor` | Comprobaciones de instalación y autenticación |
| `/quit` | Salir |

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:

| Modo | Edición de archivos | Comandos de shell | Ideal para |
| --- | --- | --- | --- |
| Plan | No, solo lectura | No | Explorar código y planificar un cambio |
| Ask Permissions (`default`) | Pregunta siempre | Pregunta siempre | Código desconocido o crítico |
| Auto-Edit (`auto-edit`) | Automática | Pregunta | Trabajo diario con muchas ediciones |
| Auto (`auto`) | La revisa un clasificador | Los revisa un clasificador | Sesiones largas con red de seguridad |
| YOLO (`yolo`) | Automática | Automáticos | Automatización de confianza en entornos aislados |

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:

| Archivo | Se aplica a |
| --- | --- |
| `~/.qwen/QWEN.md` | Ti, en todos los proyectos |
| `QWEN.md` en la raíz del proyecto | Todo el equipo (súbelo al repositorio) |
| `.qwen/QWEN.local.md` | Solo a ti, solo en este proyecto (añádelo tú a `.gitignore`) |

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.

```markdown
# 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](/es/blog/claude-md-agents-md/ "CLAUDE.md y AGENTS.md"), y vale igual para `QWEN.md`.

## Paso 7: servidores MCP

Los [servidores MCP](/es/blog/what-is-mcp-server/ "Qué es un servidor 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`:

```bash
# 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:

```bash
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:

```bash
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](/es/agents/qwen-code/ "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](/es/features/workspace/ "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](/es/features/flows/ "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](/es/download/ "Descargar 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.

## Preguntas frecuentes

**¿Qwen Code es gratis?** La CLI es gratuita y de código abierto bajo Apache-2.0, pero el plan gratuito de Qwen OAuth se retiró el 15 de abril de 2026. Ahora pagas por el modelo: un plan de QwenCloud o de Alibaba Cloud Model Studio, una API key de pago por uso o un proveedor externo. Un modelo local con Ollama no cuesta nada más allá de tu hardware.

**¿Qwen Code puede usar modelos que no sean de Qwen?** Sí. Habla los formatos de API de OpenAI, Anthropic y Gemini, muestra en /auth proveedores externos como DeepSeek, Kimi, Z.AI, MiniMax y OpenRouter, y acepta cualquier endpoint propio compatible con OpenAI, incluidos servidores locales como Ollama, vLLM y LM Studio.

**¿Qwen Code lee AGENTS.md?** Sí. Qwen Code carga ~/.qwen/QWEN.md, el QWEN.md del proyecto y .qwen/QWEN.local.md, y si el repositorio ya tiene un AGENTS.md para otras herramientas, también lo lee. No necesitas copiar las mismas reglas en dos archivos.

**¿Qué pasó con el comando qwen auth?** Se eliminó. Inicia qwen y ejecuta /auth dentro de la sesión para elegir o cambiar de proveedor, y /doctor para ver qué autenticación está activa. En scripts, define las variables de entorno del proveedor o declara el proveedor en ~/.qwen/settings.json.

**¿Cómo ejecuto Qwen Code en CI?** Usa el modo headless: qwen -p "tu prompt" con --output-format json para obtener una salida legible por máquinas. Añade un modo de aprobación como --approval-mode auto-edit, o --yolo solo en un runner aislado, porque --yolo no activa ningún sandbox. Límites como --max-wall-time detienen una ejecución que se cuelga.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/