Documentación API de Configuración

Name: Gemini CLI
Author: Google

Documentación de referencia completa de la API de gestión de configuración

Gestión de Configuración25 min de lectura

Jerarquía de Configuración

Gemini CLI utiliza un sistema de configuración jerárquico que admite múltiples fuentes de configuración y actualizaciones dinámicas

Configuración por Defecto

Valores de configuración por defecto incorporados

Prioridad: Más bajo

Archivo de Configuración Global

~/.gemini/config.toml

Prioridad: Bajo

Archivo de Configuración de Proyecto

./gemini.toml o ./.gemini/config.toml

Prioridad: Medio

Variables de Entorno

Variables de entorno con prefijo GEMINI_*

Prioridad: Alto

Argumentos de Línea de Comandos

Argumentos de tiempo de ejecución pasados al comando

Prioridad: Más alto

Opciones de Configuración

Descripción detallada de las opciones de configuración

[api]

Configuración relacionada con la API de Gemini

Opción	Tipo	Predeterminado	Descripción
`key`Requerido	string	-	Clave de API de Google AI
`model`	string	`"gemini-pro"`	Modelo predeterminado a usar
`temperature`	number	`0.7`	Temperatura de generación (0-1)
`max_tokens`	number	`4096`	Número máximo de tokens
`timeout`	number	`30000`	Tiempo de espera de solicitud en milisegundos

[session]

Configuración de gestión de sesiones

Opción	Tipo	Predeterminado	Descripción
`auto_save`	boolean	`true`	Guardar sesiones automáticamente
`max_history`	number	`100`	Número máximo de mensajes de historial
`storage_path`	string	`"~/.gemini/sessions"`	Ruta de almacenamiento de sesiones
`compression`	boolean	`true`	Habilitar compresión de sesiones

[context]

Configuración de procesamiento de contexto

Opción	Tipo	Predeterminado	Descripción
`max_files`	number	`50`	Número máximo de archivos
`max_file_size`	string	`"1MB"`	Tamaño máximo de archivo por archivo
`exclude_patterns`	array	`.log,.tmp`	Patrones de exclusión de archivos
`auto_detect_language`	boolean	`true`	Detectar automáticamente el lenguaje de programación

[plugins]

Configuración del sistema de plugins

Opción	Tipo	Predeterminado	Descripción
`enabled`	boolean	`true`	Habilitar sistema de plugins
`auto_load`	boolean	`true`	Cargar plugins automáticamente
`plugin_paths`	array	`~/.gemini/plugins`	Rutas de búsqueda de plugins
`security_mode`	string	`"strict"`	Modo de seguridad (strict/permissive)

Ejemplo de Archivo de Configuración

Ejemplo completo de archivo de configuración TOML

# Archivo de Configuración Gemini CLI (gemini.toml)

[api]
key = "your-api-key-here"
model = "gemini-pro"
temperature = 0.7
max_tokens = 4096
timeout = 30000

[session]
auto_save = true
max_history = 100
storage_path = "~/.gemini/sessions"
compression = true

[context]
max_files = 50
max_file_size = "1MB"
exclude_patterns = [
  "*.log",
  "*.tmp",
  "node_modules/**",
  ".git/**"
]
auto_detect_language = true

[plugins]
enabled = true
auto_load = true
plugin_paths = [
  "~/.gemini/plugins",
  "./plugins"
]
security_mode = "strict"

[logging]
level = "info"
file = "~/.gemini/logs/gemini.log"
max_size = "10MB"
max_files = 5

[ui]
theme = "auto"
color = true
progress_bar = true
confirm_destructive = true

Interfaz de API de Configuración

Definición de interfaz de la clase ConfigManager

ConfigManager

Definición de interfaz de la clase ConfigManager

interface ConfigManager {
  // Obtener valor de configuración
  get<T>(key: string): T | undefined
  get<T>(key: string, defaultValue: T): T

  // Establecer valor de configuración
  set(key: string, value: any): void

  // Eliminar elemento de configuración
  delete(key: string): void

  // Verificar si existe el elemento de configuración
  has(key: string): boolean

  // Obtener todas las configuraciones
  getAll(): Record<string, any>

  // Recargar configuración
  reload(): Promise<void>

  // Guardar configuración en archivo
  save(): Promise<void>

  // Observar cambios de configuración
  watch(key: string, callback: (value: any) => void): void

  // Dejar de observar cambios de configuración
  unwatch(key: string, callback?: (value: any) => void): void

  // Validar configuración
  validate(): ConfigValidationResult
}

Variables de Entorno

Lista de variables de entorno soportadas

`GEMINI_API_KEY`

Clave de API de Google AI

Ejemplo:

export GEMINI_API_KEY="your-api-key"

Configuración Correspondiente:

api.key

`GEMINI_MODEL`

Nombre del modelo predeterminado

Ejemplo:

export GEMINI_MODEL="gemini-pro"

Configuración Correspondiente:

api.model

`GEMINI_TEMPERATURE`

Temperatura de generación

Ejemplo:

export GEMINI_TEMPERATURE="0.7"

Configuración Correspondiente:

api.temperature

`GEMINI_CONFIG_PATH`

Ruta del archivo de configuración

Ejemplo:

export GEMINI_CONFIG_PATH="/path/to/config.toml"

Configuración Correspondiente:

N/A

`GEMINI_LOG_LEVEL`

Nivel de registro

Ejemplo:

export GEMINI_LOG_LEVEL="debug"

Configuración Correspondiente:

logging.level

`GEMINI_PLUGIN_PATH`

Ruta de plugins

Ejemplo:

export GEMINI_PLUGIN_PATH="/path/to/plugins"

Configuración Correspondiente:

plugins.plugin_paths

Ejemplos de Uso

Ejemplos de aplicación práctica de gestión de configuración

Operaciones Básicas de Configuración

Lectura y configuración de valores de configuración

import { ConfigManager } from '@gemini-cli/core'

const config = new ConfigManager()

// Obtener valores de configuración
const apiKey = config.get('api.key')
const model = config.get('api.model', 'gemini-pro')

// Establecer valores de configuración
config.set('api.temperature', 0.8)
config.set('session.auto_save', false)

// Guardar configuración
await config.save()

Observación de Configuración

Escuchar cambios de configuración

// Observar cambios de clave API
config.watch('api.key', (newKey) => {
  console.log('API key changed:', newKey)
  // Reinicializar cliente
  reinitializeClient(newKey)
})

// Observar cambios de modelo
config.watch('api.model', (newModel) => {
  console.log('Model changed to:', newModel)
})

Validación de Configuración

Validar la validez de la configuración

// Validar configuración
const validation = config.validate()

if (!validation.isValid) {
  console.error('Configuration errors:')
  validation.errors.forEach(error => {
    console.error(`- ${error.path}: ${error.message}`)
  })
  process.exit(1)
}

console.log('Configuration is valid')

Actualizaciones Dinámicas de Configuración

Actualizaciones de configuración en tiempo de ejecución

// Actualización dinámica de configuración
async function updateConfig(updates: Record<string, any>) {
  for (const [key, value] of Object.entries(updates)) {
    config.set(key, value)
  }

  // Validar nueva configuración
  const validation = config.validate()
  if (!validation.isValid) {
    throw new Error('Invalid configuration')
  }

  // Guardar configuración
  await config.save()

  console.log('Configuration updated successfully')
}

Consideraciones de Seguridad

Mejores prácticas para la seguridad de configuración

Seguridad de Claves API

Mejores prácticas para proteger claves API

Usar variables de entorno para almacenar claves API
Evitar codificar claves en archivos de configuración
Establecer permisos de archivo apropiados (600)
Rotar claves API regularmente

Permisos de Archivos de Configuración

Configuraciones de seguridad para archivos de configuración

Establecer archivos de configuración como solo lectura (chmod 600)
Evitar confirmar configuraciones sensibles en control de versiones
Usar .gitignore para excluir archivos de configuración
Revisar regularmente el contenido de archivos de configuración

Seguridad de Plugins

Consideraciones de seguridad para configuración de plugins

Habilitar modo de seguridad estricto
Verificar fuentes y firmas de plugins
Limitar el alcance de permisos de plugins
Actualizar regularmente las versiones de plugins

Validación de Configuración

Reglas de validación de configuración e implementación

// Reglas de validación de configuración
const configSchema = {
  api: {
    key: {
      type: 'string',
      required: true,
      minLength: 10,
      pattern: /^[A-Za-z0-9_-]+$/
    },
    model: {
      type: 'string',
      enum: ['gemini-pro', 'gemini-pro-vision'],
      default: 'gemini-pro'
    },
    temperature: {
      type: 'number',
      min: 0,
      max: 1,
      default: 0.7
    }
  },
  session: {
    max_history: {
      type: 'number',
      min: 1,
      max: 1000,
      default: 100
    },
    storage_path: {
      type: 'string',
      required: true
    }
  }
}

// Validar configuración
function validateConfig(config: any): ConfigValidationResult {
  const errors: ConfigError[] = []

  // Validar configuración API
  if (!config.api?.key) {
    errors.push({
      path: 'api.key',
      message: 'API key is required'
    })
  }

  if (config.api?.temperature < 0 || config.api?.temperature > 1) {
    errors.push({
      path: 'api.temperature',
      message: 'Temperature must be between 0 and 1'
    })
  }

  return {
    isValid: errors.length === 0,
    errors
  }
}

Continuar Aprendiendo

Explorar el protocolo MCP y desarrollo de extensiones

Introducción al Protocolo MCP Arquitectura de Extensiones Volver a la Documentación