Tutorial 7: Konfigurationsdateien

Willkommen zurück, Agenten-Flüsterer! In diesem Tutorial tauchen wir ins Herz von Hermes ein: die Konfigurationsdateien. Falls du dich schon einmal in einem Meer aus YAML und Umgebungsvariablen verloren gefühlt hast – keine Sorge, wir machen das so schmerzfrei wie möglich.

Die Hermes-Zentrale

Alles lebt in ~/.hermes/. Stell es dir als die Wohnung deines Agenten vor. So sieht es darin aus:

~/.hermes/
├── config.yaml     # Einstellungen (Modell, Terminal, TTS, Komprimierung, etc.)
├── .env            # API-Schlüssel und Geheimnisse
├── auth.json       # OAuth-Provider-Anmeldedaten (Nous Portal, etc.)
├── SOUL.md         # Primäre Agentenidentität (Slot #1 im Systemprompt)
├── memories/       # Persistenter Speicher (MEMORY.md, USER.md)
├── skills/         # Vom Agenten erstellte Fähigkeiten (verwaltet über skill_manage-Tool)
├── cron/           # Geplante Aufgaben
├── sessions/       # Gateway-Sitzungen
└── logs/           # Protokolle (errors.log, gateway.log — Geheimnisse werden automatisch geschwärzt)

Der einfachste Weg: Ein-Befehl-Setup

Bevor wir ins Eingemachte gehen, hier ein Profi-Tipp: Führe hermes setup --portal aus. Ein einziger OAuth-Login verschafft dir einen Modell-Provider und alle vier Tool-Gateway-Werkzeuge, ohne auch nur eine einzige YAML-Datei anzufassen. Portal-Abonnenten erhalten außerdem 10 % Rabatt auf token-abgerechnete Provider. Es ist der faule Weg, um loszulegen – und wir lieben ihn.

Deine Konfiguration verwalten

Hermes bietet dir ein komplettes Werkzeugset zur Verwaltung deiner Einstellungen. Hier sind die Befehle, die du täglich nutzen wirst:

hermes config              # Aktuelle Konfiguration anzeigen
hermes config edit         # config.yaml im Editor öffnen
hermes config get KEY      # Einen aufgelösten Wert ausgeben
hermes config set KEY VAL  # Einen bestimmten Wert setzen
hermes config unset KEY    # Einen benutzerdefinierten Wert entfernen
hermes config check        # Auf fehlende Optionen prüfen (nach Updates)
hermes config migrate      # Fehlende Optionen interaktiv hinzufügen

Hier sind einige praktische Beispiele:

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-...  # Wird in .env gespeichert

Der Zaubertrick: hermes config set leitet Werte automatisch an die richtige Datei weiter. API-Schlüssel landen in .env, alles andere in config.yaml. Kein Rätselraten mehr!

Was gewinnt bei einem Konflikt?

Hermes löst Einstellungen in dieser Reihenfolge auf (höchste Priorität zuerst):

CLI-Argumente — wie hermes chat --model anthropic/claude-sonnet-4
~/.hermes/config.yaml — deine primäre Konfigurationsdatei
~/.hermes/.env — für Geheimnisse (API-Schlüssel, Tokens, Passwörter)
Eingebaute Standardwerte — sichere, fest codierte Werte

Faustregel: Geheimnisse gehören in .env. Alles andere kommt in config.yaml. Wenn beides gesetzt ist, gewinnt config.yaml für Nicht-Geheimnis-Einstellungen.

Umgebungsvariablen-Substitution

Du kannst in config.yaml mit der ${VAR_NAME}-Syntax auf Umgebungsvariablen verweisen:

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

delegation:
  api_key: ${DELEGATION_KEY}

Mehrfachreferenzen funktionieren ebenfalls: url: "${HOST}:${PORT}". Wenn eine Variable nicht gesetzt ist, bleibt der Platzhalter unverändert und eine Warnung wird protokolliert. Die Cursor-artige ${env:VAR_NAME}-Syntax funktioniert ebenfalls, sodass du Ausschnitte aus Cursor- oder Claude-Konfigurationen ohne Änderungen übernehmen kannst.

Provider-Timeout

Du kannst Timeouts pro Provider und pro Modell festlegen:

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

Es gibt außerdem stale_timeout_seconds zur Erkennung veralteter Nicht-Streaming-Aufrufe. Diese Einstellungen überschreiben die veralteten HERMES_API_TIMEOUT- und HERMES_API_CALL_STALE_TIMEOUT-Umgebungsvariablen.

Laufzeitlimits

Für langlebige Server-Oberflächen (Gateway, hermes serve --isolated) kannst du Dateideskriptor-Limits festlegen:

runtime:
  nofile_soft_limit: 4096

Der Standardwert ist 4096. Setze ihn auf 0, false oder null, um die Anpassung zu deaktivieren.

Update-Verhalten

Update-Einstellungen leben unter updates in config.yaml:

updates:
  pre_update_backup: quick

Zusammenfassung

Das war die Konfigurations-Tour! Denk dran: hermes setup --portal für den einfachen Weg, hermes config set für schnelle Änderungen, und bewahre Geheimnisse in .env auf. Dein Agent wird es dir danken.

Als Nächstes: Wir erkunden KI-Provider und wie du deine Lieblingsmodelle anbindest. Bleib dran!