Qwen Code: el agente de programación en terminal con Ollama

#Qué es Qwen Code y por qué ejecutarlo en local

Qwen Code es un fork de Gemini CLI, el agente de terminal de código abierto de Google, que el equipo Qwen ha adaptado a sus modelos Qwen3-Coder. El proyecto se publica bajo la licencia Apache 2.0 en GitHub (QwenLM/qwen-code), se instala mediante npm y se utiliza con el comando qwen. Recupera la mecánica de los agentes de código modernos: un modelo recibe tu solicitud, dispone de herramientas (lectura y escritura de archivos, búsqueda en el repositorio, ejecución de shell, solicitudes web y servidores MCP) y repite el proceso con esas herramientas hasta producir un resultado verificable.

De forma predeterminada, Qwen Code se dirige a una conexión «Qwen OAuth»: te identificas con una cuenta de Qwen y las solicitudes se envían a los servidores de Alibaba Cloud. Existe una oferta gratuita en esta vía, pero sus cuotas pueden cambiar y dependen de la región. Por eso no damos ninguna cifra aquí: la página de autenticación de la documentación oficial es la única fuente actualizada. Lo que no cambia es el otro modo, llamado «OpenAI-compatible»: Qwen Code acepta cualquier servidor que exponga la API de OpenAI, incluidos Ollama y LM Studio en tu máquina.

Confidencialidad

En el modo local, el código fuente, los comandos ejecutados y sus salidas nunca abandonan el equipo. Es el argumento decisivo para código de clientes o sujeto a un acuerdo de confidencialidad.

Coste

Ninguna cuota ni factura por token. El único coste es la electricidad y el hardware ya comprado.

Disponibilidad

Sin interrupciones del servicio ni colas en las horas punta. El agente responde mientras la GPU esté funcionando.

Desventaja

Un modelo de 7 a 30 mil millones de parámetros con cuantización Q4 no está al nivel de un modelo en la nube de varios cientos de miles de millones. Es necesario dividir las tareas con más detalle y revisar más.

#Prerrequisitos

Node.js 20 o posterior

Qwen Code es un paquete npm. Compruébelo con node --version. En Linux y macOS, nvm o fnm evitan los problemas de permisos durante la instalación global.

Ollama instalado y funcional

El daemon escucha en http://localhost:11434. Un ollama list debe responder sin errores. Si no es así, empieza por la guía de instalación de Ollama.

Un modelo que gestiona la llamada a herramientas

No es negociable: un agente de código encadena llamadas a herramientas estructuradas. Los modelos de las familias Qwen3-Coder y Qwen2.5-Coder, así como Devstral, las admiten con Ollama. Un modelo sin compatibilidad con tools producirá texto en lugar de acciones y el agente se quedará bloqueado.

Memoria de la GPU

Referencias en Q4_K_M: un 7B ocupa aproximadamente 5 GB de VRAM, un 14B aproximadamente 9 GB y un 32B aproximadamente 19 GB, sin contar el contexto. El contexto largo que necesita un agente añade varios gigabytes: calcula con margen.

Un repositorio Git

No es obligatorio, pero sí muy recomendable. El agente modifica archivos; git diff y git checkout son tu red de seguridad.

#1. Instalar Qwen Code

La instalación recomendada por el repositorio se realiza globalmente mediante npm. En macOS también se publica un paquete de Homebrew. El binario se llama qwen.

npm install -g @qwen-code/qwen-code@latest
qwen --version

brew install qwen-code
qwen --version

En el primer inicio de qwen sin configuración, la herramienta propone elegir un método de autenticación. No elijas Qwen OAuth si tu objetivo es el uso local: selecciona la opción OpenAI o, mejor aún, sal y prepara primero la configuración descrita en el siguiente paso. Siempre podrás cambiar de método más tarde con el comando /auth dentro de una sesión.

#2. Conectar Qwen Code a Ollama

Ollama expone una API compatible con OpenAI en la ruta /v1 del puerto 11434. Qwen Code lee tres variables de entorno para este modo: la URL base, una clave API y el nombre del modelo. Ollama no exige una clave, pero Qwen Code rechaza un valor vacío, así que se introduce cualquier cadena.

1. 01
   Descargar un modelo de código compatible con herramientas

   Ejemplo con Qwen3-Coder 30B-A3B, un modelo de expertos (MoE) de 30 mil millones de parámetros, de los cuales 3 mil millones están activos en cada token, lo que lo hace rápido para su tamaño. Pesa alrededor de 19 GB en Q4: necesitas 24 GB de VRAM, o una máquina Apple Silicon con al menos 32 GB unificados, para mantenerlo completamente en la GPU. En una tarjeta de 12 GB, elige mejor qwen2.5-coder:7b o un modelo de 14B.
2. 02
   Comprobar que la API de OpenAI de Ollama responde

   Una solicitud a /v1/models debe enumerar tus modelos. Si falla, Ollama no está iniciado o escucha en otra dirección.
3. 03
   Crear el archivo .env en la raíz del proyecto

   Qwen Code carga automáticamente un archivo .env presente en la carpeta actual, en una subcarpeta .qwen del proyecto o en ~/.qwen para una configuración global. Tiene prioridad el archivo más cercano a la carpeta de trabajo.
4. 04
   Iniciar qwen en el proyecto

   La parte inferior de la ventana muestra el modelo activo. Si ves el nombre de tu modelo Ollama, la conexión está hecha. Escribe una primera solicitud sencilla, por ejemplo, resumir la estructura del repositorio, para comprobar que las herramientas de lectura funcionan.

ollama pull qwen3-coder:30b
curl http://localhost:11434/v1/models

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3-coder:30b

cd mon-projet
qwen

Los mismos parámetros pueden pasarse como opciones de línea de comandos para una sesión puntual, sin tocar el archivo .env. Es práctico para probar un segundo modelo sin estropear la configuración que funciona.

qwen --openai-api-key ollama \
  --openai-base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:14b

#3. Variante: LM Studio como servidor

Si prefieres LM Studio, el principio es idéntico. Carga un modelo de código en la aplicación, abre la pestaña Developer e inicia el servidor local: escucha de forma predeterminada en el puerto 1234 y expone la misma API compatible con OpenAI. Recuerda activar la compatibilidad con las llamadas a herramientas en las opciones del servidor si aún no está marcada y configurar la longitud de contexto del modelo en la interfaz (consulta el paso siguiente).

OPENAI_API_KEY=lm-studio
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen2.5-coder-14b-instruct

El nombre del modelo que debes indicar es el identificador que muestra LM Studio en la lista de modelos cargados o que devuelve una solicitud a http://localhost:1234/v1/models. Difiere de los nombres Ollama.

#4. Ajustar la ventana de contexto: el paso que todo el mundo se salta

Es la causa número uno de los fallos de Qwen Code en local. Un agente de código envía en cada turno un prompt del sistema largo (descripción de las herramientas, reglas de comportamiento, contenido del archivo QWEN.md), después el historial de la sesión y luego los archivos leídos. Desde los primeros intercambios se superan los 10 000 tokens. Sin embargo, Ollama abre de forma predeterminada una ventana corta (4 096 tokens en las versiones recientes): todo lo que excede ese límite se trunca silenciosamente, el modelo «olvida» las instrucciones de las herramientas y empieza a responder en prosa en lugar de actuar, o repite la misma acción en bucle.

Por tanto, debes imponer un contexto de al menos 32 000 tokens. Hay dos métodos en Ollama: una variable de entorno global en el daemon o un Modelfile que fija num_ctx para un modelo concreto.

sudo systemctl edit ollama
# Ajouter dans le bloc [Service] :
# Environment="OLLAMA_CONTEXT_LENGTH=32768"
sudo systemctl restart ollama

launchctl setenv OLLAMA_CONTEXT_LENGTH 32768
# puis relancer l'application Ollama

cat > Modelfile.qwen-code <<'EOF'
FROM qwen3-coder:30b
PARAMETER num_ctx 32768
EOF
ollama create qwen3-coder-32k -f Modelfile.qwen-code
# puis OPENAI_MODEL=qwen3-coder-32k dans le .env

El segundo método es más limpio: no afecta a los demás modelos y el nombre del modelo derivado recuerda su configuración. El coste es de memoria: la caché clave-valor crece con el contexto. Para un modelo 7B en Q4, un contexto de 32 000 tokens añade aproximadamente entre 2 y 4 GB, según la arquitectura y la cuantificación de la caché. Si el modelo ya no cabe en la GPU, Ollama descarga parte de las capas en la CPU y la velocidad se desploma: vigila la columna PROCESSOR de ollama ps, que debe mostrar 100 % GPU.

En el lado de Qwen Code también existe un límite de sesión. El ajuste sessionTokenLimit del archivo de configuración limita el número acumulado de tokens de una conversación; una vez alcanzado, la herramienta te invita a comprimir el historial con /compress o a empezar desde cero con /clear. Alinea este valor con lo que tu modelo admite realmente: un límite de 32 000 para un modelo servido con num_ctx 32768 evita truncamientos silenciosos por parte de Ollama.

#5. Archivo de configuración y QWEN.md

Qwen Code lee un archivo settings.json en dos niveles: ~/.qwen/settings.json para el usuario y .qwen/settings.json en el proyecto, que tiene prioridad. Las claves más útiles para un uso local son el límite de la sesión, el modo de aprobación de las acciones y los servidores MCP. Los nombres exactos han cambiado entre versiones; el ejemplo siguiente sigue la documentación pública y debe contrastarse con la página Settings de tu versión.

{
  "sessionTokenLimit": 32000,
  "contextFileName": "QWEN.md",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/moi/mon-projet"]
    }
  }
}

El archivo QWEN.md cumple la misma función que CLAUDE.md para Claude Code o AGENTS.md para otros agentes: es la memoria permanente que se inyecta en cada sesión. Describe ahí la pila tecnológica, los comandos de compilación y prueba, las convenciones de nomenclatura y aquello que el agente no debe tocar nunca. El comando /init genera una primera versión a partir del repositorio; /memory show muestra lo que el agente ha cargado realmente.

# Projet API Facturation

- Python 3.12, FastAPI, tests avec pytest (`make test`).
- Ne jamais modifier les migrations existantes dans alembic/versions/.
- Toute nouvelle route doit avoir un test dans tests/api/.
- Style : ruff, lignes de 100 caractères max.

El modo de aprobación controla lo que el agente puede hacer sin preguntarle. De forma predeterminada, cada escritura de archivo y cada comando de shell esperan su validación. La opción --approval-mode auto-edit permite pasar las modificaciones de archivos, pero no los comandos; --yolo elimina toda confirmación. Con un modelo local que se equivoca más a menudo que un modelo en la nube, mantenga el modo predeterminado hasta tener confianza y reserve --yolo para un repositorio limpio y con los cambios confirmados.

#6. Primera sesión de trabajo

Una sesión de Qwen Code se controla en lenguaje natural, con algunos atajos. El prefijo @ inserta un archivo o una carpeta en la solicitud (@src/api/routes.py), el prefijo! ejecuta un comando de shell sin pasar por el modelo y los comandos que empiezan por / controlan la propia herramienta.

/help

Lista de los comandos disponibles en tu versión.

/auth

Cambia el método de autenticación, útil para alternar entre el uso local y la nube.

/model

Muestra o cambia el modelo durante la sesión.

/stats

Tokens consumidos y duración de la sesión: el primer reflejo cuando las respuestas se degradan.

/compress

Resume el historial para liberar contexto sin perder el hilo.

/clear

Comienza una conversación vacía; QWEN.md sigue cargado.

/init et /memory

Genera y luego inspecciona el archivo de contexto del proyecto.

/mcp

Estado de los servidores MCP configurados y herramientas que exponen.

/quit

Sale de la sesión.

Un flujo que funciona bien con un modelo local: pedir primero una lectura («explica cómo se gestiona la autenticación en @src/auth/»), después una modificación acotada («añade una comprobación de expiración del token en verify_token y una prueba correspondiente») y, por último, la verificación («ejecuta make test y corrige lo que falle»). Cada etapa cabe en unos pocos miles de tokens y el modelo mantiene el hilo. Las solicitudes del tipo «refactoriza todo el módulo» superan lo que los modelos de 7 a 30B pueden mantener de forma fiable.

Para la automatización, el modo no interactivo acepta una solicitud como argumento y devuelve el control una vez terminado. Se integra en un script o en un hook de Git.

qwen -p "Relis le diff de git diff --cached et liste les problèmes potentiels, sans modifier de fichier"

#Limitaciones de Qwen Code en local

Qwen Code está diseñado en torno a los modelos Qwen3-Coder ofrecidos por Alibaba Cloud, y eso se nota en cuanto se ejecuta con un modelo local más pequeño. Esto es lo que debes aceptar.

Prompt del sistema pesado

La herramienta envía una descripción larga de las herramientas en cada turno. En un modelo 7B, esta única instrucción ocupa una parte del contexto y de la atención del modelo, que respeta peor el formato de llamada a herramientas que los modelos más grandes. Los bucles y las respuestas en prosa en lugar de acciones son más frecuentes que con OpenCode o Aider, que tienen prompts más compactos.

Visión reservada a la nube

La compatibilidad con imágenes (capturas de pantalla, maquetas) depende de modelos de visión ofrecidos en línea. En local, solo funciona si tu servidor expone un modelo multimodal compatible, lo que no ocurre con la mayoría de los modelos de código.

Sin gestión nativa de modelos locales

A diferencia de OpenCode, que muestra los modelos Ollama en un menú, Qwen Code te pide introducir el nombre del modelo y la URL en un archivo o como opción. Cambiar de modelo implica modificar .env o volver a ejecutar con --model.

Formato de configuración cambiante

El proyecto es joven y su archivo settings.json ha cambiado de estructura a lo largo de las versiones. Un ejemplo encontrado en un foro puede haber dejado de ser válido. La documentación oficial, en la fecha de consulta, es la referencia válida.

Edición mediante reescritura

Al igual que Gemini CLI, del que deriva, Qwen Code modifica los archivos reemplazando bloques. Aider, en cambio, aplica diffs unificados y hace commit automáticamente de cada cambio, lo que facilita la lectura del historial. Si quieres un commit por modificación, Aider sigue siendo más adecuado.

A cambio, Qwen Code ofrece compatibilidad completa con MCP, comandos maduros de gestión de sesiones heredados de Gemini CLI, un modo no interactivo limpio y una integración que se extiende a los IDE mediante una extensión. Es pertinente si ya utilizas los modelos Qwen y quieres una sola herramienta para alternar entre la nube de Alibaba y tu GPU. Si el objetivo es únicamente el uso local, OpenCode o Aider requieren menos ajustes para lograr el mismo resultado. No publicamos una comparación cuantitativa: la calidad depende principalmente del modelo elegido, no del agente.

#Solución de problemas

El agente responde con texto en lugar de ejecutar acciones

O bien el modelo no admite la llamada a herramientas (consulta su ficha Ollama), o bien el contexto es demasiado corto y la descripción de las herramientas se ha truncado. Aplica el paso 4 y comprueba con ollama ps que el modelo se haya cargado con el num_ctx correcto.

Error 404 o «model not found»

El nombre de OPENAI_MODEL no coincide exactamente con ollama list. Copie y pegue el nombre con su etiqueta.

Error de conexión en localhost:11434

Ollama no está iniciado o escucha en otra interfaz (OLLAMA_HOST). Haz la prueba con curl http://localhost:11434/v1/models.

Respuestas muy lentas después de algunos intercambios

El contexto ha aumentado y el modelo se sale de la GPU. ollama ps muestra una parte en la CPU. Reduce num_ctx, cambia a un modelo más pequeño o ejecuta /compress antes en la sesión.

Qwen Code vuelve a solicitar autenticación OAuth

No se leen las variables de entorno: el .env no está en la carpeta actual ni en ~/.qwen. Ejecuta /auth en la sesión y selecciona la opción OpenAI, o pasa los parámetros en la línea de comandos para aislar el problema.

El modelo ignora QWEN.md

Comprueba con /memory show que el archivo está cargado. Si contextFileName se ha modificado en settings.json, el nombre debe coincidir.

La instalación npm falla con EACCES

Permisos insuficientes en la carpeta global de npm. Instale Node mediante nvm o fnm en lugar de usar el paquete del sistema y, después, vuelva a ejecutar la instalación.

#Para ir más allá

Qwen Code es solo uno de los agentes de terminal que aceptan un servidor local. Las siguientes guías cubren las alternativas y la elección del modelo, aspectos que este artículo deja deliberadamente de lado.

• OpenCode + Ollama: un agente de código en tu terminal
• Aider + Ollama: programar en la terminal con un agente 100 % local
• Goose (Block): el agente de IA local en tu terminal
• Mejor LLM local para programar: Devstral, Qwen3-Coder

Guía redactada el 11 de octubre de 2026; las referencias son el repositorio de GitHub y la documentación de Qwen Code, así como la documentación de Ollama. No se ha realizado ninguna medición de velocidad ni de calidad para este artículo; las referencias de memoria son órdenes de magnitud. Los comandos y nombres de claves evolucionan con las versiones: compruébelos en las páginas siguientes antes de copiarlos.

• Repositorio de GitHub QwenLM/qwen-code (README, instalación, licencia)
• Documentación oficial de Qwen Code (autenticación, settings, comandos)
• Documentación de Ollama (API compatible con OpenAI, variables de entorno)