Objetivo del tema
Comprender qué son las extensiones en Qwen Code, cómo se instalan y administran, qué puede contener una extensión y de qué manera permiten ampliar el comportamiento del agente sin modificar el núcleo de la herramienta.
Este tema se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en Qwen Code Extensions, Getting Started with Qwen Code Extensions, y en las guías de Skills, Subagents y MCP.
Una extensión en Qwen Code es un paquete instalable que puede aportar nuevas capacidades al agente. La documentación la presenta como una forma de empaquetar y distribuir funcionalidades sin tocar el código interno del CLI.
Eso significa que una extensión puede reunir varias piezas en un mismo paquete:
La idea central es simple y potente: en lugar de reconfigurar Qwen Code manualmente en cada proyecto, podés instalar una extensión que ya traiga un conjunto coherente de herramientas y comportamientos.
Una extensión no es solo “un agregado”. Es una unidad de distribución que puede llevar contexto, herramientas y flujos completos de trabajo a muchos equipos y proyectos.
Sin extensiones, muchas personalizaciones quedarían repartidas en distintos lugares: un archivo de comandos por un lado, un MCP server por otro, una skill en otra carpeta y documentación dispersa. Las extensiones resuelven ese desorden agrupando todo en una estructura instalable y compartible.
Esto resulta especialmente útil cuando:
Uno de los puntos más llamativos de la documentación oficial es la compatibilidad multiplataforma. Qwen Code puede instalar directamente extensiones provenientes del ecosistema de Gemini CLI y también plugins del Claude Code Marketplace.
Esto es importante porque amplía muchísimo el ecosistema disponible. En vez de partir desde cero, Qwen Code puede aprovechar una base ya existente de extensiones y adaptarlas a su propio formato.
La documentación aclara que, en el caso de Gemini CLI, durante la instalación se realiza una conversión automática:
gemini-extension.json se convierte a qwen-extension.jsonEso permite heredar capacidades de otros ecosistemas sin exigir que el autor de la extensión mantenga una versión separada específica para Qwen Code.
La documentación indica que, al iniciar, Qwen Code busca extensiones en esta ruta:
~/.qwen/extensions/
Cada extensión vive como una carpeta con un archivo manifiesto llamado qwen-extension.json. Un ejemplo de ubicación sería:
~/.qwen/extensions/my-extension/qwen-extension.json
Esto muestra que las extensiones se gestionan a nivel de usuario como paquetes instalados. Luego, según la configuración, pueden quedar habilitadas globalmente o solo en ciertos workspaces.
qwen-extension.jsonEl corazón de toda extensión es su manifiesto. La documentación lo presenta así:
{
"name": "my-extension",
"version": "1.0.0",
"mcpServers": {
"my-server": {
"command": "node my-server.js"
}
},
"contextFileName": "QWEN.md",
"commands": "commands",
"skills": "skills",
"agents": "agents",
"settings": [
{
"name": "API Key",
"description": "Tu API key para el servicio",
"envVar": "MY_API_KEY",
"sensitive": true
}
]
}
Este archivo le dice a Qwen Code qué debe cargar, dónde encontrarlo y qué nombre usar para identificar la extensión.
| Campo | Función |
|---|---|
name |
Nombre único de la extensión. También se usa en conflictos y visualización. |
version |
Versión declarada del paquete. |
mcpServers |
Servidores MCP que la extensión aporta. |
contextFileName |
Archivo de contexto persistente, por ejemplo QWEN.md. |
commands |
Directorio donde viven los comandos personalizados. |
skills |
Directorio con skills adicionales. |
agents |
Directorio con subagentes aportados por la extensión. |
settings |
Variables y opciones configurables expuestas por la extensión. |
Esta estructura deja ver por qué las extensiones son tan potentes: no agregan una sola cosa, sino que pueden empaquetar casi toda la personalización avanzada del agente.
Desde un punto de vista pedagógico, conviene pensar una extensión como un contenedor de capacidades. La documentación oficial deja claro que puede aportar por lo menos cuatro capas importantes:
En otras palabras: una sola extensión puede cambiar lo que Qwen Code sabe, lo que puede hacer y la forma en que decide actuar.
Qwen Code ofrece dos formas de administrar extensiones: por comandos del CLI y por slash commands dentro de una sesión interactiva.
qwen extensions install
qwen extensions uninstall
qwen extensions enable
qwen extensions disable
qwen extensions update
qwen extensions update --all
Y dentro de la sesión interactiva:
/extensions
/extensions list
/extensions install
/extensions explore Gemini
/extensions explore ClaudeCode
La documentación remarca que los comandos slash soportan hot-reloading. Esto significa que algunos cambios se aplican en caliente sin necesidad de reiniciar la aplicación completa.
La documentación oficial enumera varias fuentes válidas para instalar extensiones:
Ejemplos típicos:
qwen extensions install https://github.com/github/github-mcp-server
qwen extensions install owner/repo
qwen extensions install C:\ruta\a\mi-extension
Si la fuente es local, la documentación aclara que Qwen Code crea una copia de la extensión instalada. Por eso, si el original cambia, después conviene ejecutar qwen extensions update para traer las novedades.
Las extensiones se instalan, por defecto, como disponibles para todos los workspaces del usuario. Sin embargo, la documentación permite habilitarlas o deshabilitarlas según alcance.
Ejemplo conceptual:
qwen extensions disable mi-extension
qwen extensions enable mi-extension --scope=workspace
Esto es muy útil cuando una extensión es válida solo para ciertos repositorios y sería molesta o peligrosa en el resto.
Una extensión puede aportar comandos personalizados colocando archivos Markdown en un subdirectorio indicado por el campo commands. La documentación muestra una estructura como esta:
.qwen/extensions/gcp/
├── qwen-extension.json
└── commands/
├── deploy.md
└── gcs/
└── sync.md
Eso produciría comandos como:
/deploy/gcs:syncEs decir, una extensión puede traer su propio mini lenguaje operativo para un dominio concreto, como despliegues, infraestructura, testing o documentación.
Las skills no tienen por qué vivir solo en la carpeta del usuario o del proyecto. La documentación de skills explica que una extensión también puede aportar sus propias skills, que se cargan desde el directorio definido por el campo skills del manifiesto.
Esto tiene una ventaja práctica enorme: un equipo puede empaquetar conocimiento especializado y distribuirlo como parte de una extensión, sin pedirle a cada desarrollador que copie archivos manualmente.
Lo mismo ocurre con los subagentes. La documentación de subagents señala que para saber si una extensión aporta agentes especializados hay que revisar si qwen-extension.json incluye el campo agents.
Esto significa que una extensión puede no solo traer herramientas o prompts, sino también especialistas listos para delegar tareas concretas.
Un ejemplo conceptual sería una extensión corporativa que incluya:
Todo eso, distribuido y versionado como una sola unidad.
QWEN.mdLa guía de desarrollo de extensiones muestra además que una extensión puede proveer un archivo de contexto, normalmente llamado QWEN.md. Ese archivo se usa para aportar instrucciones persistentes al modelo en cada sesión donde la extensión esté activa.
Conviene no confundirlo con una skill ni con un prompt puntual:
La documentación para desarrolladores propone empezar con una plantilla. Un ejemplo directo es:
qwen extensions new my-first-extension mcp-server
Eso genera una estructura base como esta:
my-first-extension/
├── example.ts
├── qwen-extension.json
├── package.json
└── tsconfig.json
La idea es que el desarrollador parta de un esqueleto funcional y luego agregue MCP, comandos, contexto o skills según el caso.
linkLa guía oficial también explica un flujo muy práctico para desarrollo local. Después de instalar dependencias y compilar, se puede vincular la extensión a la instalación local de Qwen Code:
cd my-first-extension
npm install
npm run build
qwen extensions link .
Ese enlace simbólico permite iterar más rápido, porque los cambios se reflejan sin tener que reinstalar la extensión manualmente en cada ajuste.
La documentación menciona explícitamente la resolución de conflictos, sobre todo cuando comandos o nombres se superponen. La regla conceptual más importante es que la configuración del workspace tiene prioridad sobre definiciones de menor alcance.
Esto evita que una extensión instalada por el usuario pise comportamientos específicos definidos por un proyecto concreto.
El campo settings del manifiesto permite que la extensión declare variables configurables, por ejemplo claves de API. La documentación muestra que cada setting puede incluir:
Esto es importante porque una buena extensión no solo agrega potencia; también debe ofrecer una forma clara y segura de configurar sus credenciales o parámetros.
| Problema | Causa probable | Primer paso razonable |
|---|---|---|
| La extensión se instala pero no hace nada visible | Está deshabilitada o no aporta comandos visibles en esa sesión. | Listarla con /extensions o revisar su manifiesto. |
| Un comando no aparece | Directorio commands incorrecto o conflicto de nombres. |
Verificar estructura y prioridad del workspace. |
| La tool MCP no funciona | El servidor declarado por la extensión falla o está mal configurado. | Revisar el bloque mcpServers y los logs del servidor. |
| La extensión local no refleja cambios | Se instaló como copia y no se actualizó. | Usar qwen extensions update o trabajar con link. |
| Una conversión desde Gemini queda rara | La migración automática no cubre algún detalle específico. | Inspeccionar el qwen-extension.json resultante y ajustar manualmente. |
Las extensiones convierten a Qwen Code en una plataforma mucho más adaptable. Permiten empaquetar herramientas, contexto, automatizaciones y especialistas dentro de una unidad instalable que después puede compartirse entre equipos y proyectos.
En este tema vimos las ideas esenciales:
qwen-extension.json.Con esta base, el siguiente paso natural es estudiar la integración con editores como VS Code, JetBrains y Zed, donde muchas de estas capacidades empiezan a convivir con una interfaz visual.