6. Configuración con settings.json y variables de entorno

Objetivo del tema

Comprender cómo se configura Qwen Code de forma persistente, qué papel cumple settings.json, cómo intervienen las variables de entorno, qué archivos existen en los distintos niveles de configuración y cómo evitar conflictos o configuraciones difíciles de mantener.

Este tema se apoya en la documentación oficial disponible al 11 de abril de 2026, especialmente en Qwen Code Configuration, en la guía de settings del sitio y en la documentación de autenticación y trusted folders.

6.1 Por qué la configuración merece un tema propio

En los temas anteriores vimos cómo instalar Qwen Code, cómo autenticarse y cómo trabajar dentro de una sesión. Pero usar bien la herramienta a largo plazo exige algo más: una configuración clara, consistente y controlada.

La configuración define aspectos fundamentales del comportamiento del CLI, por ejemplo:

  • qué modelo usar
  • qué proveedor está activo
  • qué permisos o políticas de seguridad aplicar
  • qué herramientas o integraciones están disponibles
  • cómo se resuelve el contexto de instrucciones

Por eso settings.json no es un archivo accesorio. Es una pieza estructural del ecosistema de Qwen Code.

Una mala configuración puede hacer que el agente funcione, pero de manera impredecible. Una buena configuración vuelve el comportamiento del CLI más legible, repetible y seguro.

6.2 Las capas de configuración y su precedencia

La documentación oficial explica que Qwen Code combina varias capas de configuración y que no todas tienen la misma prioridad. Esto es crucial para entender por qué a veces un valor “no toma” o parece ser ignorado.

El orden de precedencia documentado es este, desde lo más débil hasta lo más fuerte:

  1. Valores por defecto internos de la aplicación.
  2. Archivo de valores por defecto del sistema.
  3. Archivo de configuración del usuario.
  4. Archivo de configuración del proyecto.
  5. Archivo de configuración del sistema.
  6. Variables de entorno.
  7. Argumentos de línea de comandos.

La lógica es muy importante: una capa superior puede sobrescribir a una inferior. Por eso, si algo no coincide con lo esperado, siempre hay que preguntarse desde qué capa está llegando el valor real.

Resumen conceptual de precedencia
Capa Alcance Fuerza relativa
Defaults internos Comportamiento base del programa. Baja
User settings Aplica al usuario en todos sus proyectos. Media
Project settings Aplica al proyecto actual. Media-alta
Environment variables Aplica a la sesión o entorno actual. Alta
CLI arguments Aplica al arranque concreto del comando. Muy alta

6.3 Dónde vive `settings.json`

La documentación oficial describe cuatro ubicaciones posibles para archivos de configuración persistente.

Ubicaciones de configuración documentadas
Archivo Ubicación Uso principal
System defaults /etc/qwen-code/system-defaults.json en Linux, C:\ProgramData\qwen-code\system-defaults.json en Windows o la ruta equivalente en macOS. Base global con valores iniciales para todos los usuarios.
User settings ~/.qwen/settings.json Configuración general del usuario.
Project settings .qwen/settings.json en la raíz del proyecto. Configuración específica del proyecto.
System settings /etc/qwen-code/settings.json, C:\ProgramData\qwen-code\settings.json o equivalente. Políticas globales que pueden imponerse a todos los usuarios.

En la práctica diaria del curso, los dos archivos más relevantes serán estos:

  • ~/.qwen/settings.json para preferencias personales.
  • .qwen/settings.json para ajustes específicos del proyecto.

6.4 La diferencia entre configuración del usuario y del proyecto

Esta distinción es clave. No todo debe ir al mismo archivo.

Conviene pensar así:

  • User settings para preferencias que querés mantener en todos tus proyectos.
  • Project settings para reglas, modelos, herramientas o políticas propias de un repositorio concreto.

Ejemplos típicos:

  • El editor preferido o ciertas opciones de interfaz suelen pertenecer al usuario.
  • Las políticas de seguridad o la configuración MCP de un proyecto suelen pertenecer al repositorio.

Separar estos dos niveles evita mezclar preferencias personales con decisiones del equipo o del proyecto.

6.5 La estructura general de `settings.json`

La documentación oficial indica que el formato actual de settings.json está organizado por categorías de primer nivel. Es decir, no se espera un archivo plano con claves sueltas, sino una estructura más ordenada.

Ejemplo simplificado:

{
  "general": {
    "vimMode": false
  },
  "model": {
    "name": "qwen3-coder-plus"
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

Este formato ordenado hace dos cosas:

  • ayuda a comprender mejor qué área del sistema se está modificando
  • reduce el riesgo de configuraciones caóticas o difíciles de leer

6.6 Categorías principales documentadas

La documentación de configuración enumera varias categorías en settings.json. Entre las más relevantes para un curso inicial aparecen:

  • general
  • output
  • ui
  • ide
  • privacy
  • model
  • context
  • tools
  • mcp
  • security
  • advanced
  • telemetry
  • mcpServers

No es necesario dominarlas todas desde el primer día, pero sí conviene reconocer que la configuración oficial está pensada como un sistema modular, no como un puñado de flags aislados.

6.7 Algunos ajustes que conviene conocer temprano

De toda la configuración posible, hay un grupo de ajustes que conviene reconocer cuanto antes porque aparecen con frecuencia en el uso real.

Ajustes frecuentes en una primera etapa
Categoría Setting Para qué sirve
general preferredEditor Define el editor preferido para abrir archivos.
general vimMode Activa keybindings estilo Vim.
model name Selecciona el modelo predeterminado.
privacy usageStatisticsEnabled Permite desactivar estadísticas de uso.
context fileName Define el nombre del archivo de contexto jerárquico, por defecto QWEN.md.

6.8 Variables de entorno dentro de `settings.json`

La documentación oficial aclara un punto muy importante: los strings dentro de settings.json pueden referenciar variables de entorno usando sintaxis $VAR_NAME o ${VAR_NAME}.

Ejemplo:

{
  "env": {
    "DASHSCOPE_API_KEY": "$DASHSCOPE_API_KEY"
  }
}

Esto permite no hardcodear secretos directamente en el archivo. En otras palabras, settings.json puede apoyarse en variables externas para mantenerse más limpio y más seguro.

6.9 `.env` y variables de entorno: cuándo usar cada cosa

Qwen Code puede cargar variables desde el entorno del sistema y también desde archivos .env. La documentación recomienda especialmente .qwen/.env para mantener aisladas las variables propias del CLI.

El orden de búsqueda documentado para archivos .env es este:

  1. .qwen/.env desde el directorio actual hacia arriba
  2. .env desde el directorio actual hacia arriba
  3. ~/.qwen/.env
  4. ~/.env

La búsqueda se detiene en el primer archivo encontrado. No se fusionan múltiples archivos automáticamente.

Esta regla evita ambigüedad, pero también exige disciplina: si hay varios `.env` posibles, hay que saber cuál está tomando realmente Qwen Code.

6.10 Ejemplo práctico combinando settings y `.env`

Una forma razonable de configurar el entorno es dejar la estructura en settings.json y los secretos en .env.

Ejemplo de .qwen/settings.json:

{
  "model": {
    "name": "qwen3-coder-plus"
  },
  "privacy": {
    "usageStatisticsEnabled": false
  },
  "env": {
    "DASHSCOPE_API_KEY": "$DASHSCOPE_API_KEY"
  }
}

Ejemplo de .qwen/.env:

DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxx

Este patrón es más limpio que incrustar la API key literal dentro del JSON.

6.11 La carpeta `.qwen` del proyecto

La documentación oficial explica que la carpeta .qwen no solo puede contener settings.json. También puede alojar otros archivos relacionados con el funcionamiento del CLI, como perfiles de sandbox personalizados o archivos de entorno propios del proyecto.

Desde una perspectiva práctica, conviene pensar la carpeta .qwen como el espacio local de configuración y operación de Qwen Code dentro de un repositorio.

  • .qwen/settings.json para ajustes específicos del proyecto
  • .qwen/.env para variables del entorno del CLI
  • archivos de sandbox para políticas de aislamiento más específicas

6.12 Trusted folders y por qué afectan la configuración

La documentación sobre trusted folders aclara un comportamiento importante: si una carpeta no es considerada confiable, Qwen Code puede ignorar la configuración del workspace, incluyendo .qwen/settings.json.

Este detalle importa mucho porque a veces el usuario cree que la configuración del proyecto está rota, cuando en realidad el problema es que el directorio no fue aceptado como trusted folder.

En otras palabras:

  • si el proyecto es confiable, Qwen Code puede cargar la configuración local
  • si no lo es, parte de la configuración del workspace puede ser ignorada por razones de seguridad

6.13 Variables de entorno y flags de línea de comandos

La configuración no termina en settings.json. La documentación oficial menciona también variables de entorno y flags del CLI que afectan el comportamiento de Qwen Code en tiempo de ejecución.

Ejemplos documentados:

  • NO_COLOR para desactivar colores
  • CLI_TITLE para personalizar el título del CLI
  • DEBUG o DEBUG_MODE para logging más verboso
  • GEMINI_SANDBOX como alternativa al setting de sandbox
  • --extensions, --list-extensions, --proxy, --version, --include-directories y otros flags del arranque

La lección importante es que una configuración no vive solo en el JSON. El entorno y los argumentos de arranque también forman parte del resultado final.

6.14 Context files: memoria e instrucciones jerárquicas

La documentación de configuración menciona que los archivos de contexto, por defecto llamados QWEN.md, son una parte crucial de la configuración instruccional o “memoria” del agente. Aunque no son estrictamente settings.json, sí forman parte del sistema de personalización de comportamiento.

Esto quiere decir que la configuración del agente no se limita a parámetros técnicos. También incluye instrucciones persistentes sobre cómo debe trabajar dentro del proyecto.

Más adelante el curso profundizará esta parte, pero ya desde ahora conviene reconocer que:

  • settings.json configura comportamiento técnico y operativo
  • QWEN.md o el archivo de contexto equivalente configura comportamiento instruccional

6.15 Buenas prácticas para configurar Qwen Code

Con toda esta flexibilidad, es fácil desordenar el entorno si no se sigue un criterio claro. Estas prácticas suelen dar buenos resultados:

  • Dejar preferencias globales en ~/.qwen/settings.json.
  • Dejar reglas del proyecto en .qwen/settings.json.
  • No guardar secretos sensibles en texto plano dentro del JSON si podés evitarlos.
  • Usar .qwen/.env para variables específicas del CLI.
  • Revisar la precedencia cuando un valor parece ignorado.
  • Confirmar si el proyecto está marcado como trusted folder.

6.16 Errores frecuentes de configuración

Algunos problemas típicos no son fallas del producto, sino malentendidos sobre precedencia, ubicación o mezcla de capas.

Errores típicos y causa probable
Problema Causa probable Primer paso razonable
El cambio en .qwen/settings.json no surte efecto La carpeta no es trusted o una capa superior sobrescribe el valor. Revisar trusted folders, variables de entorno y argumentos del CLI.
Una credencial no se detecta El archivo .env cargado no es el que se creía o la variable está mal nombrada. Verificar el orden de búsqueda y el nombre exacto de la variable.
La configuración del proyecto afecta otros repositorios El ajuste se escribió en el archivo del usuario, no en el del proyecto. Mover el setting al nivel correcto.
El comportamiento cambia según cómo se lanza Qwen Code Los argumentos de línea de comandos están sobrescribiendo el JSON. Revisar flags y comandos de arranque.

6.17 Síntesis final

La configuración de Qwen Code combina archivos JSON, variables de entorno, argumentos de arranque y contexto jerárquico. Entender esa arquitectura es clave para usar el CLI de manera consistente y profesional.

En este tema vimos las ideas centrales:

  1. settings.json se organiza por categorías y puede existir en distintos niveles.
  2. La precedencia entre capas determina qué valor termina aplicándose realmente.
  3. ~/.qwen/settings.json y .qwen/settings.json cumplen funciones distintas.
  4. Las variables de entorno y los archivos .env son parte esencial del sistema de configuración.
  5. Trusted folders, flags y archivos de contexto influyen directamente en el comportamiento del agente.

Con esta base ya estamos listos para avanzar al siguiente tema, donde veremos approval modes, permisos y seguridad operativa en Qwen Code.

Retornar