2026 Hermes Agent – Die vollständigste Installations- und Konfigurationsanleitung: Checklisten-Tutorial mit Praxisfall
Hermes-Tutorials scheitern oft daran, dass sie vollständig wirken, aber nicht abnahmefähig sind. Dieser Leitfaden ordnet Installation, Konfiguration, Erststart und einen Praxisfall in sechs Phasen — jede Zeile nennt Prüfaktion, Bestehenskriterium und wo Sie bei einem Fehlschlag zuerst nachsehen.
Vielleicht haben Sie den Installationsbefehl schon ausgeführt, aber der API-Schlüssel fehlt. Oder der Start klappt, die Berechtigungen sind zu weit gefasst und die Logs sind unbekannt. Eine vollständige Einrichtung sollte phasenweise abgenommen werden: Erst wenn Umgebung, Installation, Modell, Berechtigungen, Logs und Praxisfall grün sind, gilt Hermes Agent als wirklich einsatzbereit.
Kurzfassung: Unter macOS empfiehlt die offizielle Doku ein Einzeiler-Installationsskript (Voraussetzung: Git); Konfiguration liegt unter ~/.hermes/; Gesundheitscheck mit hermes doctor; den Praxisfall nur in einem dedizierten Testverzeichnis ausführen — kein Vollzugriff auf die Platte.
Gesamt-Checkliste: von 0 bis zum durchlaufenden Praxisfall
Die sechs Phasen der Reihe nach abhaken. Erst wenn alles passt, Gateway, Cron oder ein echtes Repository anbinden.
| Phase | Kern-Abnahme | Befehl / Pfad |
|---|---|---|
| ① Vorbereitung | Git, Netz, Testverzeichnis, API-Account bereit | git --version, ~/hermes-workspace |
| ② Installation | hermes --version ok, Verzeichnisstruktur stimmt |
offizielles install.sh, ~/.local/bin/hermes |
| ③ Konfiguration | Provider, Modell, .env, Arbeitsverzeichnis, Logs | hermes setup, ~/.hermes/.env |
| ④ Erststart | Modell-Ping, Datei-R/W, Logs, Neustart | hermes, hermes doctor |
| ⑤ Praxisfall | Zusammenfassung + Todos, Logs, Rollback | sample.txt im Testordner |
| ⑥ Fehlersuche / Abschluss | Schichtweise prüfen, Rechte vor Erweiterung straffen | ~/.hermes/logs/ |
1. Checkliste vor der Installation
Bevor Sie irgendeinen curl-Befehl kopieren: Die folgende Tabelle Zeile für Zeile abhaken. Beim offiziellen Git-Installer ist Git die einzige harte Voraussetzung; Python 3.11, Node.js v22, uv, ripgrep und ffmpeg übernimmt das Skript.
| ☐ | Prüfaktion | Bestehenskriterium | Bei Fehlschlag zuerst |
|---|---|---|---|
| ☐ | macOS und Chip prüfen | Apple Silicon oder Intel; Systemversion entspricht der aktuellen offiziellen Installationsdoku | Systemupdate oder pip-/Nix-Pfad |
| ☐ | git --version |
Versionsausgabe; sonst xcode-select --install oder Git per Homebrew |
Xcode CLT / Homebrew |
| ☐ | Netzwerk testen | curl -I https://raw.githubusercontent.com und die gewählte LLM-Provider-Domain erreichbar |
Proxy, DNS, Firmen-Firewall |
| ☐ | Speicherplatz | Mindestens 5–10 GB frei (venv, Node, Browser-Automation) | ~/Library/Caches aufräumen |
| ☐ | LLM-Account und API-Key | Empfohlen: OpenRouter (flexibel) oder Anthropic/OpenAI; Key im Passwortmanager, nicht in Chat oder Screenshots | Provider-Konsole: Guthaben, Region |
| ☐ | Test-Arbeitsbereich anlegen | mkdir -p ~/hermes-workspace/{inbox,outbox,scratch,backups} und chmod 700 ~/hermes-workspace |
Pfad, Dateirechte |
| ☐ | Alte Konfiguration sichern (bei Neuinstallation) | Vorhandenes ~/.hermes/ als tar unter backups/ |
Nicht rm -rf ~/.hermes ohne Backup |
| ☐ | Beispieltext für Praxisfall | ~/hermes-workspace/inbox/sample.txt existiert (200–500 Wörter, UTF-8) |
Dateikodierung |
2. Installations-Checkliste
Offizieller macOS-Befehl (Stand Doku Mai 2026):
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Alternativen: pip install hermes-agent (PyPI, v0.14+); Nix laut offizieller Nix-Anleitung. Installationspfad per HERMES_INSTALL_DIR anpassbar — Details in der Doku.
| ☐ | Prüfaktion | Bestehenskriterium | Bei Fehlschlag zuerst |
|---|---|---|---|
| ☐ | Befehlsquelle prüfen | URL zeigt auf NousResearch/hermes-agent, Pfad main/scripts/install.sh |
Keine unbekannten Ein-Klick-Skripte |
| ☐ | Installationsausgabe beobachten | Kein fataler Fehler; clone/venv/uv/Node ohne Abbruch | Timeout → erneut; Rechte → kein sudo ohne Grund |
| ☐ | Nach source ~/.zshrc: which hermes |
Pfad ~/.local/bin/hermes (per-user) |
PATH, Terminal neu öffnen |
| ☐ | hermes --version oder hermes doctor |
CLI liefert Version/Diagnose, kein command not found |
System-Python vs. venv-Launcher |
| ☐ | Layout prüfen | Code unter ~/.hermes/hermes-agent/, Daten ~/.hermes/ |
HERMES_HOME unbeabsichtigt gesetzt? |
| ☐ | Laufzeit-Abhängigkeiten | hermes doctor zeigt Python, Node, ripgrep grün oder mit Fix-Hinweis |
Fehlende Pakete; ggf. hermes update |
3. Konfigurations-Checkliste
Hauptdateien: ~/.hermes/config.yaml (Einstellungen) und ~/.hermes/.env (API-Keys). Erstes Mal am besten den vollen Assistenten:
hermes setup # Vollständiger Assistent
# oder einzeln:
hermes model # Provider und Modell
hermes tools # Tools aktivieren/deaktivieren
hermes config set KEY value
| ☐ | Prüfaktion | Bestehenskriterium | Bei Fehlschlag zuerst |
|---|---|---|---|
| ☐ | LLM-Provider | Nach hermes model enthält config.yaml model.default; OpenRouter: OPENROUTER_API_KEY in .env |
Key-Tippfehler, Region, Guthaben |
| ☐ | Schlüsseldatei-Rechte | chmod 600 ~/.hermes/.env; kein Klartext-Key in yaml |
Key in git oder yaml? |
| ☐ | Arbeitsverzeichnis | MESSAGING_CWD=~/hermes-workspace (oder absoluter Pfad) in .env |
Pfad fehlt, iCloud-Sync-Ordner |
| ☐ | Terminal-Backend und Freigaben | Testphase: terminal.backend: local + approvals.mode: manual; Produktion später docker/ssh |
YOLO oder GATEWAY_ALLOW_ALL_USERS? |
| ☐ | Log-Pfad | ~/.hermes/logs/ existiert, beschreibbar, nicht in Dropbox/iCloud |
Speicher voll, Rechte |
| ☐ | Tool-Set | hermes tools nur für den Praxisfall (Dateien, Terminal); Browser/Gateway später |
Zu viele Tools → größere Angriffsfläche |
| ☐ | Konfig-Vollständigkeit | hermes config check ok; nach Upgrade ggf. hermes config migrate |
Versions-Sprung ohne migrate |
4. Checkliste für den Erststart
cd ~/hermes-workspace
hermes # Interaktive CLI
| ☐ | Prüfaktion | Bestehenskriterium | Bei Fehlschlag zuerst |
|---|---|---|---|
| ☐ | Modell-Ping | Kurzer Prompt („Hallo, antworte OK“) → sinnvolle Antwort; kein API key not set |
hermes model, .env-Variablen, Statusseite |
| ☐ | Datei lesen/schreiben | Agent legt scratch/ping.txt an und liest zurück — nur im Arbeitsbereich |
cwd, macOS-TCC, abgelehnte Freigabe |
| ☐ | Log-Schreiben | Nach Dialog neue Einträge unter ~/.hermes/logs/ |
Log-Level, Verzeichnisrechte |
| ☐ | Terminal schließen und neu öffnen | hermes startet, Konfiguration bleibt |
PATH in Shell-Profil |
| ☐ | Nach Mac-Neustart (optional) | CLI weiter nutzbar; bei hermes gateway install launchd laut Doku |
launchctl list | grep hermes, Gateway-Logs |
| ☐ | hermes doctor Abschluss |
Keine blockierenden Punkte; Installationsart erkannt | Doctor-Hinweise einzeln, nicht blind neu installieren |
5. Praxisfall-Checkliste: Zusammenfassung + Todo-Extraktion
Erste abnahmefähige Aufgabe im Testverzeichnis. Kein Produktions-Repo, keine Cloud-Konsole, kein ~/Documents.
5.1 Eingabe vorbereiten
cat > ~/hermes-workspace/inbox/sample.txt <<'EOF'
Projekt-Weekly (Testsample)
- Anna: API-Doku v2 bis nächste Woche
- Ben: Login-403 bis Mittwoch beheben
- Chris: Hermes Agent vs. OpenClaw vergleichen, Freitag berichten
EOF
cp ~/hermes-workspace/inbox/sample.txt ~/hermes-workspace/backups/sample.txt.bak
5.2 Aufgaben-Prompt (in hermes CLI einfügen)
Lies inbox/sample.txt und erzeuge in outbox/ zwei Dateien:
1) summary.md — Zusammenfassung unter 200 Wörtern
2) todos.md — Markdown-Todo-Liste mit Verantwortlichen und Fristen
Ändere die Originaldatei in inbox nicht und greife nicht außerhalb des Arbeitsbereichs zu.
| ☐ | Prüfaktion | Bestehenskriterium | Bei Fehlschlag zuerst |
|---|---|---|---|
| ☐ | Ausgabedateien | outbox/summary.md und outbox/todos.md vorhanden, Inhalt zu Namen/Daten passend |
Freigabe pending, Modell-Halluzination |
| ☐ | Original unverändert | diff inbox/sample.txt backups/sample.txt.bak ohne Unterschied |
Prompt, Tool-Rechte |
| ☐ | Logs nachvollziehbar | Session mit Tool-Aufrufen in den Logs | Log-Pfad, Log-Level |
| ☐ | Rollback | rm outbox/*.md → Aufgabe erneut erfolgreich; Backup intakt |
Session-Cache, Dateisperre |
| ☐ | Kosten | Token-Verbrauch in Provider-Konsole plausibel; Spend-Limit gesetzt (falls verfügbar) | Zu großes Modell, Tool-Schleife |
| ☐ | Berechtigungsgrenze | Kein Zugriff auf ~/.hermes/.env oder ~/.ssh; riskante Befehle → manual |
tools, Freigabemodus |
6. Fehlersuche: schichtweise — nicht sofort neu installieren
Probleme von oben nach unten abarbeiten. „Installiert, geht nicht“ ist meist PATH, Key oder cwd — selten ein kaputtes Hermes-Paket.
| Schicht | Symptom | Zuerst prüfen | Typische Lösung |
|---|---|---|---|
| Abhängigkeiten | hermes: command not found |
PATH, ~/.local/bin |
source ~/.zshrc |
| Netzwerk | Installation/Modell-Timeout | curl GitHub, Provider-API | Proxy, DNS, anderes Netz |
| Key | API key not set |
~/.hermes/.env |
hermes model / hermes config set |
| Provider | 401/429/5xx | Statusseite, Guthaben, Modell-ID | Modell wechseln, Limit, später retry |
| Berechtigungen | Datei nicht schreibbar / Befehl abgelehnt | cwd, Freigabe-Warteschlange, macOS TCC | Freigeben, Arbeitsverzeichnis korrigieren |
| Pfade | config nicht gefunden | HERMES_HOME, Mehrbenutzer |
HERMES_HOME vereinheitlichen |
| Logs | Stilles Scheitern | ~/.hermes/logs/, errors.log |
Konfig gezielt anpassen |
| Hintergrunddienst | Gateway antwortet nicht | launchd, Token, Allowlist | hermes gateway, Gateway-Doku |
7. Abschluss-Checkliste: vor dem echten Workflow
- ☐
~/.hermes/erneut sichern (config, skills; keine Keys in Klartext-Archiven) - ☐
approvals.modeweiterhin manual oder teamkonform - ☐ Gateway: Allowlist / DM-Pairing gesetzt, kein
GATEWAY_ALLOW_ALL_USERS - ☐ Spend-Limit und Alerts in der Provider-Konsole
- ☐ outbox-Ausgaben manuell stichprobenartig prüfen, dann erst echtes Repo
- ☐ Offizielle Security-Doku lesen, bevor Tools oder Terminal-Backend erweitert werden
Sind alle Phasen grün, können Sie Telegram-Gateway, Cron oder CI anbinden. Für engere Mac-Grenzen bei Schlüsseln und Berechtigungen siehe unseren Hermes-Agent-Mac-Sicherheitsleitfaden.
Hermes auf dem Mac mini — Abnahme mit weniger Risiko
Hermes Agent braucht Git, Python, Node und Unix-Terminal-Tools — unter macOS nativ, ohne WSL. Ein dedizierter Mac mini trennt CLI-Tests, Gateway und Logs vom Alltags-MacBook; die Unified Memory von Apple Silicon hilft bei lokalen Hilfsrouten (z. B. Ollama), Gatekeeper, SIP und FileVault liefern Systemschutz.
Der Mac mini M4 verbraucht im Leerlauf etwa 4 W, bleibt lüfterlos leise — ideal als 7×24-Agent-Knoten; mit hermes gateway install kann launchd nach Neustart wieder anlaufen. Wenn Sie diese Checkliste durchgehen, ist der Mac mini M4 einer der klarsten Hardware-Einstiege — jetzt zugreifen und jede Abnahmezeile auf stabiler Hardware abhaken.