Tutorial 7: File di Configurazione

Bentornati, domatori di agenti! In questo tutorial ci immergiamo nel cuore di Hermes: i file di configurazione. Se vi siete mai sentiti persi in un mare di YAML e variabili d’ambiente, niente paura: renderemo tutto il più indolore possibile.

La Base di Hermes

Tutto vive in ~/.hermes/. Pensatelo come l’appartamento del vostro agente. Ecco cosa c’è dentro:

~/.hermes/
├── config.yaml     # Impostazioni (modello, terminale, TTS, compressione, ecc.)
├── .env            # Chiavi API e segreti
├── auth.json       # Credenziali provider OAuth (Nous Portal, ecc.)
├── SOUL.md         # Identità primaria dell'agente (slot #1 nel prompt di sistema)
├── memories/       # Memoria persistente (MEMORY.md, USER.md)
├── skills/         # Skill create dall'agente (gestite tramite lo strumento skill_manage)
├── cron/           # Job pianificati
├── sessions/       # Sessioni gateway
└── logs/           # Log (errors.log, gateway.log — i segreti vengono automaticamente oscurati)

Il Percorso Più Semplice: Configurazione con un Comando

Prima di addentrarci nei dettagli, ecco un consiglio da professionisti: eseguite hermes setup --portal. Un solo OAuth vi dà un provider di modelli e tutti e quattro gli strumenti del Tool Gateway senza toccare un singolo file YAML. Gli abbonati al Portal ricevono anche il 10% di sconto sui provider a pagamento a token. È il modo più pigro per iniziare, e lo adoriamo.

Gestire la Vostra Configurazione

Hermes vi offre un kit completo per gestire le impostazioni. Ecco i comandi che userete quotidianamente:

hermes config              # Visualizza la configurazione corrente
hermes config edit         # Apre config.yaml nel vostro editor
hermes config get KEY      # Stampa un valore risolto
hermes config set KEY VAL  # Imposta un valore specifico
hermes config unset KEY    # Rimuove un valore impostato dall'utente
hermes config check        # Controlla le opzioni mancanti (dopo gli aggiornamenti)
hermes config migrate      # Aggiunge interattivamente le opzioni mancanti

Ecco alcuni esempi pratici:

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-...  # Viene salvato in .env

Il trucco magico: hermes config set instrada automaticamente i valori nel file giusto. Le chiavi API vanno in .env, tutto il resto va in config.yaml. Niente più congetture!

Cosa Vince Quando C’è un Conflitto?

Hermes risolve le impostazioni in questo ordine (priorità dalla più alta alla più bassa):

Argomenti CLI — come hermes chat --model anthropic/claude-sonnet-4
~/.hermes/config.yaml — il vostro file di configurazione principale
~/.hermes/.env — per i segreti (chiavi API, token, password)
Valori predefiniti integrati — valori hardcoded sicuri

Regola pratica: I segreti vanno in .env. Tutto il resto va in config.yaml. Quando entrambi sono impostati, config.yaml vince per le impostazioni non segrete.

Sostituzione delle Variabili d’Ambiente

Potete fare riferimento alle variabili d’ambiente in config.yaml usando la sintassi ${VAR_NAME}:

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

delegation:
  api_key: ${DELEGATION_KEY}

Anche i riferimenti multipli funzionano: url: "${HOST}:${PORT}". Se una variabile non è impostata, il segnaposto rimane così com’è e viene registrato un avviso nel log. Funziona anche la sintassi in stile Cursor ${env:VAR_NAME}, quindi potete copiare frammenti dalle configurazioni di Cursor o Claude senza modifiche.

Timeout dei Provider

Potete impostare i timeout per ogni provider e per ogni modello:

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

Esiste anche stale_timeout_seconds per rilevare chiamate non in streaming rimaste inattive. Queste impostazioni sovrascrivono le variabili d’ambiente legacy HERMES_API_TIMEOUT e HERMES_API_CALL_STALE_TIMEOUT.

Limiti di Runtime

Per le superfici server a lunga esecuzione (gateway, hermes serve --isolated), potete impostare i limiti dei descrittori di file:

runtime:
  nofile_soft_limit: 4096

Il valore predefinito è 4096. Impostatelo a 0, false o null per disabilitare la regolazione.

Comportamento degli Aggiornamenti

Le impostazioni di aggiornamento vivono sotto updates in config.yaml:

updates:
  pre_update_backup: quick

Per Concludere

Questo era il tour della configurazione! Ricordate: hermes setup --portal per il percorso facile, hermes config set per modifiche rapide, e tenete i segreti in .env. Il vostro agente vi ringrazierà.

Prossimo passo: esploreremo i provider di IA e come collegare i vostri modelli preferiti. Restate sintonizzati!