Objetivo del tema
Comprender cómo ejecutar Qwen Code fuera de la interfaz conversacional, cómo usar su modo headless desde scripts, tuberías o pipelines, y qué opciones permiten transformar al CLI en una herramienta de automatización reutilizable.
Este tema se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en Headless Mode, en la documentación de configuración del CLI y en la guía general del frontend de línea de comandos.
La documentación oficial usa también la palabra headless para referirse al modo no interactivo. En este modo, Qwen Code se ejecuta sin abrir una interfaz conversacional continua en terminal. Recibe una entrada, la procesa, devuelve un resultado y termina.
Esto cambia el modelo de uso:
La documentación lo presenta como una interfaz orientada a:
Headless mode convierte a Qwen Code en una herramienta que puede integrarse en otros flujos, no solo en una experiencia de chat en terminal.
La documentación oficial indica que el camino estándar para usar headless mode es pasar un prompt directamente por línea de comandos con --prompt o su forma corta -p.
qwen --prompt "¿Qué es el fine tuning?"
qwen -p "resume la arquitectura de este proyecto"
El comportamiento esperado es simple:
Este patrón es la base de casi toda automatización con el CLI.
La documentación también indica que Qwen Code puede leer entrada estándar. Esto permite encadenarlo con otras herramientas de la terminal usando pipes.
echo "explica este código" | qwen
Esto resulta muy útil cuando otro comando genera la entrada que querés analizar con Qwen Code.
Ejemplos típicos:
cat README.md | qwen -p "resume esta documentación"
git diff | qwen -p "revisa estos cambios buscando errores y riesgos"
Con esto ya se vuelve evidente por qué headless mode es tan importante: permite componer Qwen Code con el ecosistema tradicional de herramientas de consola.
Aunque ambos enfoques sirven para automatizar, no son exactamente lo mismo.
| Mecanismo | Conviene cuando | Ejemplo |
|---|---|---|
--prompt |
La consulta principal ya está definida en la línea de comando. | qwen -p "analiza este repositorio" |
| stdin | Otra herramienta produce el contenido que querés analizar. | cat archivo.txt | qwen |
| Ambos combinados | Querés pasar contenido por stdin y además una instrucción explícita. | cat README.md | qwen -p "resume esto" |
La guía oficial de headless mode documenta varios formatos de salida, controlados por --output-format o -o.
qwen -p "resume este proyecto" --output-format text
qwen -p "resume este proyecto" --output-format json
qwen -p "resume este proyecto" --output-format stream-json
La diferencia es clave:
text: salida humana legible, útil para uso directo.json: salida estructurada, ideal para scripts.stream-json: eventos estructurados en flujo, útil para integraciones más avanzadas.La documentación explica además que en json la salida se entrega al final, mientras que en stream-json se puede procesar progresivamente.
Cuando se usa stream-json, la documentación documenta el flag --include-partial-messages para incluir mensajes parciales durante la generación.
qwen -p "analiza este diff" --output-format stream-json --include-partial-messages
Este detalle importa para integraciones donde querés mostrar progreso o consumir eventos a medida que llegan, en lugar de esperar la respuesta completa.
Además del formato de salida, la documentación de headless mode menciona --input-format. Esto permite indicar explícitamente si la entrada se interpreta como texto normal o como flujo JSON.
qwen --input-format text --output-format stream-json
Este tipo de opción no siempre hará falta en ejemplos simples, pero es importante para integraciones más sofisticadas donde otro proceso produce datos estructurados.
Una de las capacidades más potentes de la documentación reciente es que headless mode puede continuar la sesión más reciente del proyecto o reanudar una sesión específica por ID. Eso permite automatizaciones multi-paso sin perder contexto previo.
qwen --continue -p "ejecuta las pruebas otra vez y resume los errores"
qwen --resume 123e4567-e89b-12d3-a456-426614174000 -p "termina el refactor pendiente"
La documentación oficial aclara que las conversaciones se almacenan por proyecto bajo ~/.qwen/projects/<cwd-sanitized>/chats, en formato JSONL.
Esto transforma el modo no interactivo en algo mucho más potente que una simple llamada aislada: también puede operar sobre estados de trabajo previos.
La documentación de headless mode incluye opciones para ampliar explícitamente el contexto de archivos.
qwen -p "analiza este proyecto" --all-files
qwen -p "documenta esta base" --include-directories src,docs
Su sentido es el siguiente:
--all-files: incluye todo el árbol de archivos relevante en el contexto.--include-directories: agrega directorios concretos que querés asegurar dentro del análisis.Conviene usarlos con criterio, porque cuanto más contexto se fuerza, más costosa y potencialmente más lenta puede volverse la ejecución.
El headless mode no elimina las decisiones de seguridad. La documentación incluye flags como:
qwen -p "haz el refactor" --approval-mode auto_edit
qwen -p "aplica los cambios y ejecuta pruebas" --yolo
Esto es importante porque muchas automatizaciones no pueden depender de aprobaciones humanas en tiempo real. Sin embargo, la decisión de volver más permisiva la ejecución debe seguir tratándose con mucha cautela, igual que en modo interactivo.
La combinación entre headless mode y permisos define el nivel real de automatización.
La guía oficial menciona --debug o -d para activar un modo de diagnóstico más detallado.
qwen -p "resume este error" --debug
La documentación también destaca que headless mode ofrece códigos de salida consistentes para facilitar el manejo de errores en scripts. Esto es muy importante en automatización seria, porque no alcanza con “ver” el texto: el proceso que invoca a Qwen Code necesita saber si la ejecución fue exitosa o falló.
La documentación oficial incluye varios ejemplos muy representativos. Adaptados al contexto del curso, muestran bien la potencia del modo headless.
Revisión de código desde un diff:
git diff origin/main...HEAD | qwen -p "revisa estos cambios en busca de bugs, riesgos de seguridad y problemas de calidad" --output-format json
Generación de mensaje de commit:
git diff --cached | qwen -p "escribe un mensaje de commit breve y claro para estos cambios" --output-format json
Análisis de logs:
grep "ERROR" app.log | tail -20 | qwen -p "analiza estos errores y sugiere causa raíz y correcciones"
Notas de release a partir de commits:
git log --oneline v1.0.0..HEAD | qwen -p "genera notas de versión a partir de estos commits" --output-format json
Estos ejemplos muestran por qué la documentación insiste en que headless mode es ideal para scripts y pipelines.
No todas las tareas ganan con headless mode. Conviene usarlo especialmente cuando:
En cambio, si todavía estás explorando el proyecto o ajustando ideas, la sesión interactiva suele ser mejor punto de partida.
| Escenario | Modo recomendado | Razón principal |
|---|---|---|
| Entender un repositorio | Interactivo | Necesitás ida y vuelta exploratoria. |
| Generar release notes cada semana | Headless | Es una tarea repetible y automatizable. |
| Analizar errores de logs desde cron | Headless | No requiere conversación continua. |
| Diseñar un refactor grande | Interactivo | Conviene discutir por etapas. |
La documentación no solo muestra flags; también sugiere implícitamente un criterio de uso. Estas prácticas suelen dar buenos resultados:
--include-directories o entrada por stdin cuando haga falta.--continue o --resume para flujos largos o por etapas.Los problemas más comunes en esta etapa suelen venir de malentendidos sobre entrada, contexto o expectativas de salida.
| Problema | Causa probable | Primer paso razonable |
|---|---|---|
| La salida no sirve para un script | Se usó formato text en vez de JSON. | Repetir con --output-format json. |
| El análisis parece superficial | Falta contexto o entrada relevante. | Usar stdin, --all-files o --include-directories. |
| La automatización pierde continuidad | La ejecución no reutiliza una sesión previa. | Usar --continue o --resume. |
| El proceso no puede completarse sin intervención | El approval mode elegido sigue requiriendo confirmaciones. | Revisar --approval-mode o --yolo con criterio. |
El modo no interactivo transforma a Qwen Code en una herramienta de automatización real. Permite ejecutar prompts desde línea de comandos o stdin, producir salidas estructuradas, continuar sesiones previas y encadenarse con el resto del ecosistema de herramientas de consola.
En este tema vimos las ideas centrales:
--prompt y stdin son las dos puertas de entrada básicas al modo headless.--output-format y --input-format controlan cómo se integra Qwen Code con scripts y pipelines.--continue y --resume permiten automatización con continuidad de contexto.--all-files y --include-directories ayudan a controlar el contexto de análisis.Con esta base, el siguiente paso natural es estudiar las skills, instrucciones reutilizables y comandos personalizados que permiten adaptar Qwen Code a flujos todavía más específicos.