Tutorial 7: Archivos de Configuración

¡Bienvenidos de nuevo, domadores de agentes! En este tutorial, nos sumergimos en el corazón de Hermes: los archivos de configuración. Si alguna vez te has sentido perdido en un mar de YAML y variables de entorno, no temas—vamos a hacer esto lo más indoloro posible.

La Base de Operaciones de Hermes

Todo vive en ~/.hermes/. Piénsalo como el apartamento de tu agente. Esto es lo que hay dentro:

~/.hermes/
├── config.yaml     # Ajustes (modelo, terminal, TTS, compresión, etc.)
├── .env            # Claves API y secretos
├── auth.json       # Credenciales de proveedores OAuth (Nous Portal, etc.)
├── SOUL.md         # Identidad principal del agente (slot #1 en el prompt del sistema)
├── memories/       # Memoria persistente (MEMORY.md, USER.md)
├── skills/         # Habilidades creadas por el agente (gestionadas con la herramienta skill_manage)
├── cron/           # Trabajos programados
├── sessions/       # Sesiones de gateway
└── logs/           # Registros (errors.log, gateway.log — secretos automáticamente redactados)

El Camino Más Fácil: Configuración con un Solo Comando

Antes de meternos en la maleza, aquí va un consejo de profesional: ejecuta hermes setup --portal. Un solo OAuth te consigue un proveedor de modelos y las cuatro herramientas del Tool Gateway sin tocar ni un solo archivo YAML. Los suscriptores de Portal también reciben un 10% de descuento en proveedores con facturación por tokens. Es la forma perezosa de empezar, y nos encanta.

Gestionando Tu Configuración

Hermes te da un kit completo de herramientas para gestionar ajustes. Estos son los comandos que usarás a diario:

hermes config              # Ver la configuración actual
hermes config edit         # Abrir config.yaml en tu editor
hermes config get KEY      # Imprimir un valor resuelto
hermes config set KEY VAL  # Establecer un valor específico
hermes config unset KEY    # Eliminar un valor establecido por el usuario
hermes config check        # Comprobar opciones faltantes (después de actualizaciones)
hermes config migrate      # Añadir interactivamente opciones faltantes

Aquí tienes algunos ejemplos prácticos:

hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...  # Se guarda en .env

El truco mágico: hermes config set enruta automáticamente los valores al archivo correcto. Las claves API van a .env, todo lo demás va a config.yaml. ¡No más adivinanzas!

¿Qué Gana Cuando Hay un Conflicto?

Hermes resuelve los ajustes en este orden (mayor prioridad primero):

Argumentos CLI — como hermes chat --model anthropic/claude-sonnet-4
~/.hermes/config.yaml — tu archivo de configuración principal
~/.hermes/.env — para secretos (claves API, tokens, contraseñas)
Valores predeterminados integrados — valores seguros codificados

Regla general: Los secretos van en .env. Todo lo demás va en config.yaml. Cuando ambos están establecidos, config.yaml gana para ajustes no secretos.

Sustitución de Variables de Entorno

Puedes hacer referencia a variables de entorno en config.yaml usando la sintaxis ${VAR_NAME}:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

Las referencias múltiples también funcionan: url: "${HOST}:${PORT}". Si una variable no está establecida, el marcador de posición se queda tal cual y se registra una advertencia. La sintaxis estilo Cursor ${env:VAR_NAME} también funciona, así que puedes copiar fragmentos de configuraciones de Cursor o Claude sin cambios.

Tiempos de Espera de Proveedores

Puedes establecer tiempos de espera por proveedor y por modelo:

providers:
  some-provider:
    request_timeout_seconds: 600
    models:
      some-model:
        timeout_seconds: 300

También existe stale_timeout_seconds para detectar llamadas no streaming obsoletas. Estos ajustes anulan las variables de entorno heredadas HERMES_API_TIMEOUT y HERMES_API_CALL_STALE_TIMEOUT.

Límites de Ejecución

Para superficies de servidor de larga duración (gateway, hermes serve --isolated), puedes establecer límites de descriptores de archivo:

runtime:
  nofile_soft_limit: 4096

El valor predeterminado es 4096. Establécelo a 0, false o null para desactivar el ajuste.

Comportamiento de Actualización

Los ajustes de actualización viven bajo updates en config.yaml:

updates:
  pre_update_backup: quick

Conclusión

¡Ese es el recorrido por la configuración! Recuerda: hermes setup --portal para el camino fácil, hermes config set para cambios rápidos, y mantén los secretos en .env. Tu agente te lo agradecerá.

Lo siguiente: exploraremos los proveedores de IA y cómo conectar tus modelos favoritos. ¡Mantente atento!