4. Configuración de Gemini CLI

Objetivo del tema

Personalizar Gemini CLI para distintos proyectos y perfiles de trabajo, conociendo el formato de settings.json, las opciones más relevantes y las estrategias para combinar configuraciones locales, globales y de línea de comandos.

La configuración oficial se actualizará durante 2025 con un esquema reorganizado; este repaso se basa en la versión vigente en la documentación estable.

4.1 Archivo de configuración: ubicación y formato

Gemini CLI lee ajustes persistentes desde archivos JSON escalonados. El orden de precedencia va de menor a mayor (los niveles superiores sobrescriben a los inferiores):

Nivel	Ubicación por defecto	Uso recomendado
System defaults	/etc/gemini-cli/system-defaults.json (Linux), C:\ProgramData\gemini-cli\system-defaults.json (Windows), /Library/Application Support/GeminiCli/system-defaults.json (macOS)	Valores base definidos por administradores. Puede redefinirse con GEMINI_CLI_SYSTEM_DEFAULTS_PATH.
User settings	~/.gemini/settings.json	Preferencias del usuario actual (tema, editor, modelo por defecto).
Project settings	.gemini/settings.json en la raíz del proyecto	Configura el CLI para un repositorio específico; ideal para estandarizar herramientas y contexto.
System overrides	/etc/gemini-cli/settings.json (o ruta definida en GEMINI_CLI_SYSTEM_SETTINGS_PATH)	Capas de control corporativo: fuerza políticas que priman sobre las demás.
Variables de entorno	.gemini/.env, ~/.gemini/.env o exportes manuales	Ajustes temporales o secretos (API keys, proxies, sandbox).
Argumentos CLI	Flags de ejecución (por ejemplo gemini --proxy ...)	Control inmediato para una sesión puntual.

El archivo settings.json usa una estructura jerárquica por categorías (general, ui, model, etc.). Puedes interpolar variables de entorno en cualquier string usando $VAR o ${VAR}.

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "customWittyPhrases": [
      "Connecting to AGI",
      "Listo para revisar tu repo"
    ]
  },
  "tools": {
    "sandbox": "docker",
    "exclude": ["write_file"]
  },
  "model": {
    "name": "gemini-1.5-pro-latest",
    "maxSessionTurns": 10
  },
  "context": {
    "fileName": ["CONTEXT.md", "GEMINI.md"],
    "loadFromIncludeDirectories": true
  }
}

El CLI migrará automáticamente configuraciones antiguas al nuevo formato en los próximos lanzamientos. Revisa la sección “Configuration v1” si mantienes entornos legados.

4.2 Opciones configurables destacadas

Las opciones disponibles abarcan desde preferencias visuales hasta integraciones corporativas. A continuación agrupamos las más utilizadas:

• General y UI: activa general.vimMode, define general.preferredEditor, ajusta el tema (ui.theme) o esconde elementos como ui.hideBanner, ui.hideFooter y ui.showLineNumbers.
• Modelo y sesiones: selecciona el modelo principal con model.name, limita el historial mediante model.maxSessionTurns y activa resúmenes automáticos de herramientas con model.summarizeToolOutput.
• Contexto: controla el archivo de memoria (context.fileName), los directorios incluidos (context.includeDirectories) o la profundidad de descubrimiento (context.discoveryMaxDirs). Usa /memory show y /memory refresh para validar el resultado.
• Entorno y herramientas: elige el motor sandbox con tools.sandbox (por ejemplo docker), registra comandos de descubrimiento personalizados o excluye herramientas sensibles (tools.exclude).
• Telemetría y privacidad: habilita o desactiva registros con telemetry.enabled, telemetry.target, telemetry.otlpEndpoint y controla el uso de estadísticas anónimas mediante privacy.usageStatisticsEnabled.
• Accesibilidad: activa ui.accessibility.screenReader o aprovecha la bandera --screen-reader para ajustar la TUI.

En ejecuciones puntuales, combina la configuración persistente con flags como:

• --proxy para establecer un proxy corporativo.
• --telemetry, --telemetry-target y --telemetry-otlp-endpoint para redirigir la instrumentación.
• --approval-mode y --allowed-tools para reforzar políticas de seguridad.
• --include-directories para sumar rutas contextuales sin editar archivos.

Cuando trabajes con endpoints de Vertex AI, recuerda que las variables GOOGLE_CLOUD_PROJECT y GOOGLE_CLOUD_LOCATION siguen activas desde el tema de autenticación y complementan la configuración del modelo.

4.3 Configuración avanzada: sobrescrituras y perfiles múltiples

Para equipos y organizaciones es habitual combinar varios niveles de configuración:

• Perfiles por proyecto: almacena .gemini/settings.json, contextos y scripts en cada repositorio. Complementa con un archivo .gemini/.env para variables sensibles que el CLI cargará automáticamente.
• Variables por sesión: exporta valores específicos antes de invocar el comando:

  export GEMINI_CONTEXT_DEBUG=true
  gemini --debug

• Sobrescrituras centrales: los administradores pueden fijar límites globales con GEMINI_CLI_SYSTEM_SETTINGS_PATH o distribuir un system-defaults.json endurecido.
• Sandbox personalizado: crea .gemini/sandbox.Dockerfile para incluir dependencias propias y construye la imagen al vuelo:

  FROM gemini-cli-sandbox
  # Agrega paquetes o configuraciones corporativas aquí

  BUILD_SANDBOX=1 gemini -s

• Memoria jerárquica: combina contextos globales (~/.gemini/GEMINI.md), de proyecto y de subdirectorios. Ajusta context.discoveryMaxDirs si el repositorio es muy grande.

Cuando necesites depurar una configuración:

• Ejecuta gemini --debug para inspeccionar la carga de archivos y variables.
  
• Verifica el orden aplicado con /memory show (para contexto) y revisa el contenido de ~/.config/gemini/logs si habilitaste telemetría local.
  
• Si un valor no se actualiza, revisa que no haya un override superior (por ejemplo, un sistema corporativo) o un flag en la invocación actual.

Conclusión: dominar los archivos settings.json, las variables de entorno y los flags de ejecución te permite crear perfiles precisos para cada escenario: desde desarrollos personales hasta pipelines empresariales. El siguiente paso es aplicar estas configuraciones a los flujos de uso cotidiano del CLI.