Hermes Agent: Das Praxisreferenzhandbuch (2026)

Kurzfassung: Hermes Agent ist ein selbstverbessernder Open-Source-AI-Agent von Nous Research. Er läuft als CLI und als plattformübergreifendes Messaging-gateway, speichert eine dauerhafte Identität und persistente Memory auf der Festplatte, bündelt skills, die sich durch Nutzung verbessern, und arbeitet mit jedem OpenAI-kompatiblen LLM-Provider — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok oder Ihrem eigenen selbst gehosteten Endpoint.¹²¹⁹ Seit v0.14.0 (16. Mai 2026) ergänzt Hermes SuperGrok OAuth mit grok-4.3 1M Context, einen OpenAI-kompatiblen lokalen proxy für OAuth-Provider (hermes proxy), erstklassiges x_search, PyPI-Installationssupport, lazy Dependency-Installationen, 22 Messaging-Plattformen mit LINE und SimpleX Chat, /handoff, semantische LSP-Diagnosen nach Schreibvorgängen, einheitliches video_generate, computer_use über cua-driver für Nicht-Anthropic-Provider, native Windows-Beta sowie 12 P0- und 50 P1-Abschlüsse.¹⁹ Der schwierigste Teil für die meisten neuen Benutzer ist die Provider-Authentifizierung: Hermes unterstützt etwa 20 erstklassige Provider plus benutzerdefinierte Endpoints und 3 verschiedene Auth-Pfade (API-Schlüssel in .env, OAuth über hermes model oder benutzerdefinierter Endpoint in config.yaml). Das Auth-Modell sollten Sie zuerst verstehen — alles andere hängt davon ab, welcher Provider aufgelöst wird.

Hermes Agent arbeitet als vollständige Agent-Runtime, nicht als Chat-Wrapper. Er liest Ihr Dateisystem, führt Befehle in sandboxed Backends aus, scraped das Web, startet Subagents, führt geplante cron-Jobs aus, kommuniziert über Telegram/Discord/Slack/WhatsApp/Signal/Email aus einem einzigen gateway-Prozess heraus und erstellt aus Erfahrung eigene skills.¹ Die CLI ist eine Terminal-UI auf Basis einer Conversation Loop in run_agent.py; das gateway ist ein lang laufender Prozess, der Nachrichten von Messaging-Plattformen durch dieselbe Conversation Loop routet.³

Der Unterschied zwischen gelegentlicher und professioneller Hermes-Nutzung liegt in 5 Systemen. Beherrschen Sie diese, wird Hermes zu einem Kraftmultiplikator:

1. Provider-Auflösung: wie Auth-Flows auf API-Aufrufe abgebildet werden
2. Konfigurationshierarchie: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Tool- + toolset-System: was der Agent tun kann, je Plattform eingeschränkt
4. skills-System: prozedurale Memory, die der Agent erstellt und weiterentwickelt
5. gateway + cron + profile: Hermes dort ausführen, wo Sie arbeiten, nicht nur dort, wo Sie gerade sind

Wichtige Erkenntnisse

• Provider-Auth besteht aus 3 Pfaden, nicht aus einem. API-Schlüssel in .env, OAuth über hermes model/hermes auth oder benutzerdefinierter Endpoint in config.yaml. Wählen Sie den Pfad, der zu Ihrem Provider passt, nicht den, der Ihnen vertraut vorkommt.
• Provider-Wechsel erfolgen mit einem einzigen Befehl. hermes model führt Sie interaktiv durch jeden unterstützten Provider einschließlich OAuth-Logins, und /model provider:model wechselt mitten in der Sitzung, ohne den Verlauf zu verlieren.²
• 2 Dateien bilden die vom Benutzer editierbare Konfigurationsoberfläche. ~/.hermes/config.yaml enthält Einstellungen, ~/.hermes/.env enthält Secrets. auth.json, SOUL.md, MEMORY.md und skills/ werden direkt von Hermes verwaltet — Sie können SOUL.md von Hand bearbeiten, den Rest verändert der Agent selbst.⁴
• Hermes ist der Nachfolger von OpenClaw. Wenn Sie migrieren, importiert hermes claw migrate automatisch mehr als 30 Zustandskategorien.⁵
• Die Servicequalität hängt von Ihrem Hilfsmodell ab. Vision, Web-Zusammenfassung, Compression und Memory Flush verwenden alle ein separates Hilfs-LLM. Standardmäßig ist das Gemini Flash über Auto-Erkennung (OpenRouter → Nous → Codex) — wenn keiner davon konfiguriert ist, verschlechtern sich diese Funktionen stillschweigend, bis Sie die Hilfs-Slots auf Ihren Hauptprovider verweisen lassen.⁴

Was v0.14 ändert

v0.14.0 dreht sich weniger um eine einzelne Hauptfunktion als darum, den Setup-Aufwand zu reduzieren und zugleich zu erweitern, wo Hermes laufen kann.¹⁹ Die wichtigsten betrieblichen Änderungen:

• Installation und Start sind leichter. pip install hermes-agent funktioniert über PyPI, schwere Adapter werden bei der ersten Nutzung lazy installiert, und der Startpfad verzögert genug Arbeit, um den Kaltstart um etwa 19 Sekunden zu verkürzen.
• Abonnements können zu lokalen API-Endpoints werden. hermes proxy verwandelt OAuth-gestützte Provider wie Claude Pro, ChatGPT Pro und SuperGrok in einen OpenAI-kompatiblen lokalen Endpoint für Tools wie Codex, Aider, Cline und Continue.
• Die gateway-Reichweite wächst. LINE und SimpleX Chat erhöhen die Plattformanzahl auf 22, Microsoft Teams ist durchgängig angebunden, Discord-Verlaufs-Backfill ist standardmäßig aktiviert, und Telegram/Discord-clarify-Prompts nutzen nun native Schaltflächen.
• Verifikation zur Schreibzeit wird besser. Nach Bearbeitungen kann Hermes pro Turn Zusammenfassungen von Dateimutationen und semantische Language-Server-Diagnosen anzeigen, bevor der nächste Turn beginnt; damit rückt es näher an evidenzgetriebene Agent-Arbeit heran.
• Desktop- und Medien-Tools werden breiter. computer_use funktioniert über cua-driver für Nicht-Anthropic-Provider, video_generate ist einheitlich hinter austauschbaren Backends gebündelt, und vision_analyze sendet rohe Pixel an Modelle, die tatsächlich sehen können.

Jeder folgende Abschnitt stützt sich auf die Upstream-Dokumentation unter hermes-agent.nousresearch.com/docs und den Source Tree unter github.com/NousResearch/hermes-agent. Jede Tatsachenbehauptung hat eine Fußnote, die auf die konkrete Upstream-Seite verweist, von der sie stammt.

Wählen Sie Ihren Weg

So funktioniert Hermes: Das Mental Model

Hermes ist um eine einzelne Konversationsschleife herum aufgebaut, die jeder Einstiegspunkt aufrufen kann. Die Einstiegspunkte sind die CLI (cli.py), das Messaging-gateway (gateway/run.py), der ACP-Adapter für die Editor-Integration, der Batch Runner und ein API Server.³ Alle rufen letztlich AIAgent.run_conversation() in run_agent.py auf, das:

1. den System-Prompt aus SOUL.md, MEMORY.md, USER.md, skills, Kontextdateien und Tool-Hinweisen über prompt_builder.py erstellt³
2. den Runtime-Provider über runtime_provider.py auflöst — in diesem Schritt werden Ihre Authentifizierung, Base URL und der API Modus ausgewählt³
3. den Provider über einen von drei API Modi aufruft: chat_completions, codex_responses oder anthropic_messages³
4. alle zurückgegebenen Tool-Aufrufe über model_tools.py und die zentrale Tool-Registry (tools/registry.py) weiterleitet³
5. die Schleife fortsetzt, bis das Modell eine finale Antwort erzeugt, und die Sitzung anschließend mit FTS5 in SQLite speichert³

Diese Schleife zu verstehen ist wichtig, weil jede Funktion — personalities, memory, skills, compression, fallback — an eine dieser Phasen andockt. Wenn Sie einen Config-Key lesen und sich fragen, was er bewirkt, lautet die Antwort meistens: „Er ist ein Regler für Phase 1, 2, 3 oder 4 der obigen Schleife.“

Plattformunabhängiger Kern. Eine AIAgent-Klasse bedient CLI, gateway, ACP, batch und den API Server. Plattformunterschiede liegen im Einstiegspunkt, nicht im Agent selbst.³ Deshalb funktionieren dieselben Slash Commands im Terminal und in Telegram — sie werden aus einer gemeinsamen COMMAND_REGISTRY in hermes_cli/commands.py heraus ausgeführt.⁶

Die Ordnerstruktur ist das System. Hermes speichert alles unter ~/.hermes/ (oder $HERMES_HOME für nicht standardmäßige profile):⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── auth.json          # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/          # Gateway session state
└── logs/              # agent.log, gateway.log, errors.log (secrets auto-redacted)

Jede der obigen Dateien hat eine eigene Rolle; keine davon überschneidet sich mit einer anderen. Wenn Sie nach „Wo speichert Hermes X?“ suchen, liegt die Antwort in einer dieser Dateien.

Installation

Der One-Line-Installer bleibt der geführte Weg für die meisten Benutzer. Er kümmert sich um Python, uv, Node.js, ripgrep, ffmpeg, den Repo-Klon, die virtuelle Umgebung und den globalen hermes-Befehl.⁷ v0.14.0 liefert außerdem ein echtes PyPI-Paket aus, sodass pip install hermes-agent jetzt eine brauchbare Direktinstallation ist, wenn Sie die Python Umgebung bereits selbst kontrollieren.¹⁹

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

pip install hermes-agent
hermes

Funktioniert unter Linux, macOS, WSL2 und Android/Termux (der Installer erkennt Termux automatisch und wechselt zu einem getesteten Android-Bundle).⁷ v0.14.0 ergänzt native Windows-Unterstützung als frühe Beta über einen PowerShell-Installer, aber WSL2 bleibt bis zur weiteren Reife des Windows-Pfads die sicherere Empfehlung für den Produktionseinsatz.¹⁹

Nach Abschluss:

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

Die einzige Voraussetzung ist git. Der Installer stellt Python 3.11 automatisch über uv bereit (kein sudo erforderlich), dazu Node.js v22 (für Browser-Automatisierung und die WhatsApp-Bridge), ripgrep und ffmpeg.⁷

Installation überprüfen

hermes version      # Check version
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor sagt Ihnen genau, was fehlt und wie Sie es beheben.⁷ hermes dump ist der Diagnosebefehl, den Sie in ein GitHub issue oder einen Discord-Thread einfügen, wenn Sie Hilfe anfragen — eine Klartextzusammenfassung Ihrer gesamten Einrichtung, bei der Secrets unkenntlich gemacht wurden.⁸

Manuelle Installation

Wenn Sie volle Kontrolle benötigen — eine eigene Python Version, bestimmte Extras, Nix/NixOS-Integration — ist der manuelle Ablauf Schritt für Schritt im upstream installation guide dokumentiert.⁷ Wichtige optionale Extras, die Sie mit uv pip install -e ".[<extras>]" kombinieren können:

Der Termux-Installationsbefehl ist anders — er nutzt pip mit einer Constraints-Datei, nicht uv pip:

python -m pip install -e ".[termux]" -c constraints-termux.txt

Der Grund: .[all] zieht unter Android faster-whisper über das voice-Extra ein, das von ctranslate2-Wheels abhängt, die nicht für Android veröffentlicht werden.⁷

Authentifizierung & Providers

Hermes unterstützt etwa 19 erstklassige Providers plus benutzerdefinierte Endpunkte sowie drei unterschiedliche Authentifizierungspfade. Hier sehen Sie die gesamte Authentifizierungsoberfläche, nach Pfad geordnet, damit Sie schnell die passende Option für Ihre vorhandene Konfiguration finden.

Die drei Authentifizierungspfade

Jeder Provider in Hermes gehört zu einem von drei Authentifizierungsmustern:

Pfad 1 — API key in .env. Legen Sie Ihren Schlüssel in ~/.hermes/.env ab, und Hermes liest ihn beim Start ein. Verwendet von OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, MiniMax (und MiniMax China), Alibaba Cloud/DashScope, Kilo Code, OpenCode Zen, OpenCode Go, DeepSeek, Hugging Face, Google/Gemini und den meisten Drittanbieter-Providers.²

Pfad 2 — OAuth über hermes model oder hermes auth. Startet einen Device-Code-Flow, öffnet einen Browser, speichert Zugangsdaten in ~/.hermes/auth.json und kann vorhandene Zugangsdaten aus Tools wie Claude Code oder Codex CLI importieren. Verwendet von Nous Portal, OpenAI Codex (ChatGPT-Konto), GitHub Copilot und Anthropic (Claude Pro/Max).²

Pfad 3 — Benutzerdefinierter Endpunkt in config.yaml. Für jede OpenAI-kompatible API — Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM proxy, Together AI, Groq, Azure OpenAI oder Ihren eigenen selbst gehosteten Server. Einmal über hermes model → Custom endpoint konfiguriert und anschließend in config.yaml gespeichert.²

Die vollständige Provider-Matrix

Dies ist die vollständige Liste der erstklassigen Providers, jeweils mit dem exakten Einrichtungsablauf.²

Anthropic: Drei Authentifizierungsmethoden

Anthropic erhält einen eigenen Abschnitt, weil Hermes drei verschiedene Wege zu Claude unterstützt und die richtige Wahl wichtig ist. Aus der Upstream-Dokumentation:²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

Wenn Sie Anthropic OAuth über hermes model auswählen, bevorzugt Hermes den eigenen Zugangsdaten-Speicher von Claude Code, statt das Token nach ~/.hermes/.env zu kopieren. So bleiben aktualisierbare Claude-Zugangsdaten aktualisierbar.² Wenn Sie Claude Code bereits auf demselben Rechner verwenden, ist das der sauberste Pfad.

Um Anthropic dauerhaft in config.yaml festzulegen:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude und --provider claude-code funktionieren ebenfalls als Kurzformen für --provider anthropic.²

GitHub Copilot: Zwei Modi

Copilot wird in zwei Modi unterstützt: direkter Copilot API (empfohlen) und Copilot ACP, bei dem die lokale Copilot CLI als Subprozess gestartet wird.²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

Die Authentifizierung wird laut Upstream-Dokumentation in dieser Reihenfolge geprüft:² 1. Umgebungsvariable COPILOT_GITHUB_TOKEN 2. Umgebungsvariable GH_TOKEN 3. Umgebungsvariable GITHUB_TOKEN 4. gh auth token CLI-Fallback 5. OAuth Device-Code-Login über hermes model

Der Token-Typ zählt. Die Copilot API unterstützt keine klassischen Personal Access Tokens (ghp_*). Unterstützte Typen sind OAuth-Tokens (gho_*), fine-grained PATs (github_pat_* mit Berechtigung Copilot Requests) und GitHub App-Tokens (ghu_*). Wenn Ihr gh auth token ein ghp_*-Token zurückgibt, authentifizieren Sie sich stattdessen über hermes model per OAuth.²

Chinesische AI-Providers (erstklassige Unterstützung)

Hermes bietet integrierte Unterstützung für z.ai/GLM, Kimi/Moonshot, MiniMax (globale + China-Endpunkte) und Alibaba Cloud mit dedizierten Provider-IDs.²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

Basis-URLs können mit den Umgebungsvariablen GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL oder DASHSCOPE_BASE_URL überschrieben werden.²

Z.AI erkennt den Endpunkt automatisch. Bei Verwendung des z.ai/GLM-Providers prüft Hermes mehrere Endpunkte (global, China, Coding-Varianten), um einen zu finden, der Ihren API key akzeptiert. Der funktionierende Endpunkt wird automatisch zwischengespeichert — für die meisten Benutzer ist kein GLM_BASE_URL nötig.²

xAI (Grok) aktiviert Prompt-Caching automatisch. Wenn die Basis-URL x.ai enthält, sendet Hermes bei jeder Anfrage den Header x-grok-conv-id, damit innerhalb einer Konversationssitzung derselbe Server genutzt wird und zwischengespeicherte System-Prompts sowie Verlauf wiederverwendet werden.² Automatisch; keine Konfiguration erforderlich.

Der Befehl hermes auth

hermes auth ist der Befehl zur Verwaltung von Zugangsdaten für Pools und OAuth-Zugangsdaten.⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

Mit Zugangsdaten-Pools rotieren Sie mehrere API keys oder OAuth-Tokens für denselben Provider — nützlich, um Rate Limits über mehrere Schlüssel zu verteilen, ohne Code zu ändern.⁶ Die alten Befehle hermes login / hermes logout wurden entfernt; verwenden Sie stattdessen hermes auth.⁶

Benutzerdefinierte & selbst gehostete Endpunkte

Hermes funktioniert mit jedem OpenAI-kompatiblen API-Endpunkt. Wenn ein Server /v1/chat/completions implementiert, können Sie Hermes darauf verweisen.²

Interaktive Einrichtung (empfohlen):

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

Manuelle config.yaml:

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

Beide Ansätze speichern in config.yaml, der zentralen Quelle für Hauptmodell, Provider und Basis-URL.² Die alten Env Vars OPENAI_BASE_URL und LLM_MODEL werden für die Hauptmodell-Konfiguration nicht mehr gelesen — verwenden Sie hermes model oder bearbeiten Sie config.yaml direkt.² (OPENAI_BASE_URL + OPENAI_API_KEY werden weiterhin als Fallback für den Hilfs-Routingpfad provider: "main" berücksichtigt; löschen Sie sie also nicht blind, falls Sie sie dort verwenden.)⁴

Benutzerdefinierte Endpunkte während einer Sitzung wechseln:

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom (nackt, ohne Modellnamen) fragt die /v1/models API Ihres Endpunkts ab und wählt das Modell automatisch aus, wenn genau eines geladen ist — nützlich für lokale Server, auf denen ein einzelnes Modell läuft.²

Lokale LLM-Server (Einrichtungsvorlagen)

Die Upstream-Dokumentation enthält vollständige Einrichtungsanleitungen für Ollama, vLLM, SGLang, llama.cpp und LM Studio. Hier sind die wichtigsten Befehle, die Sie tatsächlich ausführen werden. Jeder ist darauf ausgelegt, einen funktionierenden Endpunkt bereitzustellen, auf den Hermes zeigen kann.²

Ollama — einfachster lokaler Pfad, keine Konfiguration:

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Kritischer Ollama-Fallstrick: Ollama verwendet standardmäßig sehr niedrige Kontextlängen (4.096 Tokens unter 24GB VRAM). Sie müssen diese über OLLAMA_CONTEXT_LENGTH oder eine Modelfile erhöhen — die OpenAI-kompatible API akzeptiert die Kontextlänge nicht vom Client, daher kann Hermes sie nicht für Sie setzen.² Für Agent-Nutzung sollten Sie mindestens 16k–32k festlegen.

vLLM — leistungsstarkes GPU-Serving:

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Tool Calling erfordert --enable-auto-tool-choice und --tool-call-parser <name>. Unterstützte Parser: hermes (Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Ohne diese Flags kommen Tool-Aufrufe als Klartext zurück.²

SGLang — schnelles Serving mit RadixAttention zur Wiederverwendung des KV-Caches:

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

SGLang-Fallstrick: Der Standardwert für max_tokens ist 128. Setzen Sie --default-max-tokens auf dem Server oder konfigurieren Sie model.max_tokens in config.yaml, wenn Antworten abgeschnitten werden.²

llama.cpp / llama-server — CPU und Apple Silicon Metal:

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

--jinja ist für Tool Calling erforderlich. Ohne diese Option ignoriert llama-server den Parameter tools vollständig, und das Modell versucht, Tools aufzurufen, indem es JSON in seinen Antworttext schreibt — was Hermes nicht als echte Tool-Aufrufe parsen kann.²

LM Studio — Desktop-App mit GUI:

Starten Sie den Server aus der LM Studio-App (Developer-Tab → Start Server) oder über CLI: lms server start (startet auf Port 1234) und lms load qwen2.5-coder --context-length 32768.² Verweisen Sie hermes model anschließend auf http://localhost:1234/v1.

Kritischer LM Studio-Fallstrick: LM Studio liest die Kontextlänge aus den Modellmetadaten, aber viele GGUF-Modelle melden Standardwerte von 2048 oder 4096. Setzen Sie die Kontextlänge in den LM Studio-Modelleinstellungen immer explizit — klicken Sie auf das Zahnradsymbol neben der Modellauswahl, setzen Sie “Context Length” auf mindestens 16384 (besser 32768), und laden Sie das Modell neu.²

Benannte benutzerdefinierte Providers

Wenn Sie mit mehreren benutzerdefinierten Endpunkten arbeiten, etwa einem lokalen Entwicklungsserver und einem entfernten GPU-Server, definieren Sie diese als benannte benutzerdefinierte Providers in config.yaml:²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

Wechseln Sie anschließend während einer Sitzung mit der Dreifach-Syntax zwischen ihnen:

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

Sie können benannte benutzerdefinierte Providers auch im interaktiven Menü von hermes model auswählen.²

Erweiterbare Provider-Architektur (v0.13.0+)

v0.13.0 liefert eine ProviderProfile ABC plus ein Verzeichnis plugins/model-providers/, sodass Drittanbieter-Inferenz-Providers ohne Änderungen am Kern integriert werden können.¹⁸ Wenn ein Provider einen OpenAI-, Anthropic- oder Codex-kompatiblen API-Modus spricht, können Sie eine ProviderProfile-Unterklasse implementieren, die Authentifizierungspfad, Basis-URL, Modellkatalog und Caching-Header deklariert; Hermes löst sie über denselben runtime_provider.py-Pfad auf, den die integrierten Providers verwenden. Das ist die Architekturänderung hinter der Provider-Erweiterung in v0.13.0: Statt den Kerncode zu bearbeiten, um einen Provider hinzuzufügen, liefern Sie ein Plugin aus.

OpenAI-kompatibler lokaler Proxy (v0.14.0+)

hermes proxy stellt einen OpenAI-kompatiblen lokalen Endpunkt bereit, der durch den OAuth-Provider gestützt wird, bei dem Hermes bereits angemeldet ist — Claude Pro, ChatGPT Pro, SuperGrok oder ein anderer kompatibler konfigurierter Provider.¹⁹ Das bedeutet: Tools, die eine OpenAI-artige API erwarten, darunter Codex CLI, Aider, Cline, Continue oder benutzerdefinierte Skripte, können Ihre abonnementgestützte Hermes-Authentifizierung ohne separaten API key wiederverwenden. Behandeln Sie den Proxy als lokale Entwicklungsinfrastruktur: Binden Sie ihn bewusst, stellen Sie ihn nicht breit erreichbar bereit, und behalten Sie providerspezifische Bedingungen im Blick.

Erkennung der Kontextlänge

Zwei Einstellungen werden laut Upstream-Dokumentation ständig verwechselt:²

• context_length — das gesamte Kontextfenster (kombiniertes Token-Budget für Eingabe + Ausgabe, z. B. 1.000.000 für Claude Opus 4.7 oder 200.000 für Sonnet 4.6). Hermes nutzt dies, um zu entscheiden, wann der Verlauf komprimiert wird.
• model.max_tokens — die Ausgabegrenze (maximale Token-Anzahl, die das Modell in einer einzelnen Antwort erzeugen darf). Unabhängig von der Verlaufslänge.

Setzen Sie context_length, wenn die automatische Erkennung die Fenstergröße falsch bestimmt:

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes nutzt eine mehrstufige Auflösungskette zur Erkennung von Kontextfenstern: Konfigurationsüberschreibung → benutzerdefinierter Provider pro Modell → persistenter Cache → Endpunkt /models → Anthropic /v1/models → OpenRouter API → Nous Portal → models.dev (community-gepflegte Registry für über 3800 Modelle) → Fallback-Standardwerte (128K).² Das System ist providerbewusst, sodass dasselbe Modell je nach Anbieter unterschiedliche Kontextlimits haben kann (z. B. ist claude-opus-4.6 direkt bei Anthropic 1M, aber bei GitHub Copilot 128K).²

Provider-Rotation & Fallback

Zugangsdaten-Pools. Wenn Sie mehrere API keys für denselben Provider haben, konfigurieren Sie über hermes auth eine Rotationsstrategie. So verteilen Sie Rate Limits über mehrere Schlüssel.⁶

Fallback-Modell. Konfigurieren Sie ein Backup provider:model, zu dem Hermes automatisch wechselt, wenn Ihr primäres Modell fehlschlägt (Rate Limits, Serverfehler, Authentifizierungsfehler):²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

Der Fallback tauscht Modell und Provider während der Sitzung aus, ohne Ihre Konversation zu verlieren. Er wird höchstens einmal pro Sitzung ausgelöst.² Unterstützte Providers für Fallback: openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.²

Hilfsmodelle

Hermes verwendet leichtgewichtige „Hilfsmodelle“ für Nebenaufgaben: Bildanalyse, Zusammenfassung von Webseiten, Analyse von Browser-Screenshots, Klassifizierung gefährlicher Befehle zur Genehmigung, Kontextkomprimierung, Zusammenfassung der Sitzungssuche, skill-Abgleich, MCP-Tool-Dispatch und Speicher-Flush.⁴ Standardmäßig verwenden diese Gemini Flash per automatischer Erkennung (OpenRouter → Nous → Codex).

Sie können konfigurieren, welches Modell und welcher Provider für jede Hilfsaufgabe verwendet wird. Jeder Hilfsslot nutzt dieselben drei Stellschrauben: provider, model, base_url.⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                       # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                    # Custom OpenAI-compatible endpoint
    api_key: ""                     # Falls back to OPENAI_API_KEY
    timeout: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

Die Provider-Option "main" bedeutet: „Verwende denselben Provider wie mein Hauptagent“ — gültig nur innerhalb von auxiliary:, compression: und fallback_model:-Konfigurationen. Sie ist nicht für Ihre oberste Einstellung model.provider gültig. Wenn Sie einen benutzerdefinierten OpenAI-kompatiblen Endpunkt als Hauptmodell verwenden, setzen Sie provider: custom in Ihrem Abschnitt model:.⁴

Warum das wichtig ist: Wenn Sie nur Anthropic OAuth konfiguriert haben (kein OpenRouter key), werden Vision, Webzusammenfassung und Komprimierung schlechter funktionieren oder fehlschlagen, weil die Standard-Fallback-Kette für Hilfsmodelle zuerst OpenRouter versucht. Fügen Sie einen OPENROUTER_API_KEY für Hilfsaufgaben hinzu oder konfigurieren Sie jeden Hilfsslot so um, dass Ihr Haupt-Provider verwendet wird:

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

Dies ist der mit Abstand häufigste Fallstrick vom Typ „Meine Funktionen funktionieren stillschweigend nicht“ für neue Hermes-Benutzer.

Konfigurationssystem

Hermes verfügt über ein mehrschichtiges Konfigurationssystem. Die Rangfolge zu verstehen ist entscheidend, weil höhere Ebenen niedrigere überschreiben und eine der Ebenen eine globale Provider-Registry ist, die Sie in config.yaml nicht sehen können.

Aufbau der Konfigurationsdateien

Laut Upstream-Dokumentation bilden diese Dateien eine Hermes-Konfiguration:⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml vs. .env — wenn beide gesetzt sind, gewinnt config.yaml bei nicht geheimen Einstellungen.⁴ Die Regel lautet: - Secrets (API keys, Bot-Tokens, Passwörter) → .env - Alles andere (Modell, Terminal-Backend, Komprimierungseinstellungen, Speicherlimits, toolsets) → config.yaml

Secrets können aus config.yaml per Shell-ähnlicher Interpolation referenziert werden:⁴

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

Konfiguration verwalten

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

Beispiele:⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check und hermes config migrate sind die Befehle, die Sie nach jedem hermes update ausführen sollten — sie erkennen neu hinzugefügte Konfigurationsoptionen, die Ihre Datei noch nicht enthält.⁶

Konfigurationsrangfolge

Hermes lädt Konfigurationen aus mehreren Quellen. Wenn mehrere Quellen denselben Wert setzen, gewinnt die Quelle mit der höheren Priorität:⁴

1. CLI-Argumente — hermes chat --model anthropic/claude-sonnet-4 (Überschreibung pro Aufruf)
2. Umgebungsvariablen — werden beim Prozessstart angewendet
3. config.yaml — die primäre Einstellungsdatei
4. .env — nur Secrets
5. Eingebaute Standardwerte — werden angewendet, wenn nichts anderes einen Wert setzt

CLI-Flags gewinnen immer für diesen einzelnen Aufruf. config.yaml ist die langfristige Quelle der Wahrheit.

Lokalisierung (v0.13.0+)

v0.13.0 fügte 7 Locales für CLI und gateway-Nachrichten hinzu: Chinesisch (vereinfacht), Japanisch, Deutsch, Spanisch, Französisch, Ukrainisch und Türkisch.¹⁸ v0.14.0 lokalisiert alle gateway-Befehle und das Web-Dashboard, fügt 8 weitere Locales hinzu und erhöht die Gesamtzahl auf 16.¹⁹ Die Dokumentation ist derzeit nur in zh-Hans lokalisiert. Das Locale wird aus den Umgebungsvariablen LC_ALL / LANG oder einem expliziten locale:-Schlüssel in config.yaml aufgelöst. Englisch bleibt der Standard und die Quelle der Wahrheit für alle Strings, die eine Übersetzung noch nicht abdeckt.

Profiles — mehrere isolierte Hermes-Instanzen

Profiles geben Ihnen mehrere isolierte Hermes-Instanzen, jeweils mit eigener Konfiguration, eigenen Sitzungen, skills, eigenem Speicher und eigener gateway-PID. So können Sie „Arbeits-Hermes“ und „persönliches Hermes“ nebeneinander betreiben, ohne dass eine Instanz den Zustand der anderen sieht.⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

Jedes profile erhält sein eigenes HERMES_HOME (standardmäßig ~/.hermes-<name>/), sodass mehrere profiles das gateway gleichzeitig ausführen können, ohne sich gegenseitig in die Quere zu kommen.⁶³

CLI-Befehle

Dieser Abschnitt dient als Praxisreferenz für die übergeordneten CLI-Befehle. Die verbindliche, aus dem Quellcode abgeleitete Referenz finden Sie in der upstream-Dokumentation CLI Commands Reference.⁶

Globale Optionen

hermes [global-options] <command> [subcommand/options]

Übergeordnete Befehle

hermes chat — Der Haupteinstiegspunkt

hermes ohne Argumente öffnet den interaktiven Chat. hermes chat ist die explizite Form mit Optionen:⁶

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

Wichtige Optionen:

hermes setup — Vollständiger Assistent

Startet den vollständigen Einrichtungsassistenten oder springt direkt in einen Abschnitt:⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs — Strukturierte Protokollabfragen

hermes logs ist leistungsfähiger als tail -f auf den Protokolldateien, da es gleichzeitig nach Level, Sitzungs-ID und Zeitraum filtern kann.⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

Die Protokolldateien befinden sich in ~/.hermes/logs/:⁶ - agent.log — sämtliche Agentenaktivitäten (API-Aufrufe, Tool-Dispatch, Sitzungslebenszyklus, INFO+) - errors.log — ausschließlich Warnungen und Fehler (gefilterte Teilmenge von agent.log) - gateway.log — Messaging-Gateway-Aktivitäten (Plattformverbindungen, Dispatch, Webhooks)

Die Rotation erfolgt automatisch über Pythons RotatingFileHandler — achten Sie auf agent.log.1, agent.log.2 usw.⁶

hermes doctor — Diagnose

hermes doctor [--fix] ist der erste Befehl, den Sie bei Problemen ausführen sollten. Er prüft die Konfigurationsvalidität, das Vorhandensein von Abhängigkeiten, die Verfügbarkeit von API-Schlüsseln sowie den Dienststatus und kann mit --fix automatische Reparaturen versuchen.⁶

Um Diagnoseinformationen mit anderen zu teilen, verwenden Sie hermes dump — dieser Befehl erzeugt eine kompakte Klartextzusammenfassung mit geschwärzten API-Schlüsseln, die Sie direkt in ein GitHub-Issue oder einen Discord-Thread einfügen können.⁶

Slash-Befehle

Slash-Befehle werden innerhalb einer aktiven Chat-Sitzung (CLI oder Messaging-Plattform) ausgeführt. Sie werden aus einer gemeinsamen COMMAND_REGISTRY in hermes_cli/commands.py heraus ausgelöst, weshalb die meisten Befehle auf allen Oberflächen identisch funktionieren.⁹

Sitzungssteuerung

Konfiguration & Modell

Der /model-Befehl ist das Arbeitspferd für den Provider-Wechsel während einer Sitzung:⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

Tools, Skills & Informationen

Dynamische Skill-Slash-Befehle

Jede installierte skill wird automatisch als Slash-Befehl verfügbar gemacht:⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

Sie können außerdem Schnellbefehle in config.yaml definieren, die einen Kurznamen als Alias für einen längeren Prompt verwenden:⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

Geben Sie anschließend /review, /deploy oder /morning in CLI ein.

Präfixabgleich

Befehle unterstützen Präfixabgleich: Die Eingabe von /h wird zu /help aufgelöst, /mod zu /model. Wenn ein Präfix mehrdeutig ist, gewinnt die erste Registrierung in Registry-Reihenfolge. Vollständige Befehlsnamen und registrierte Aliase haben immer Vorrang vor Präfixübereinstimmungen.⁹

Messaging-spezifische Befehle

Einige Befehle funktionieren nur auf Messaging-Plattformen (Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant):⁹

• /status — Sitzungsinformationen anzeigen
• /sethome (Alias /set-home) — aktuellen Chat als Plattform-Home markieren
• /approve [session|always] — ausstehenden gefährlichen Befehl genehmigen
• /deny — ausstehenden gefährlichen Befehl ablehnen
• /update — Hermes Agent auf die neueste Version aktualisieren
• /commands [page] — alle Befehle und skills durchsuchen (paginiert)

Und einige sind nur für CLI verfügbar: /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Tools & Toolsets

Hermes wird mit einer breiten integrierten Tool-Registry ausgeliefert, die Websuche, Browserautomatisierung, Terminalausführung, Dateibearbeitung, Memory, Delegation, RL-Training, Nachrichtenzustellung, Home Assistant-Integration und mehr abdeckt.¹⁰ Tools sind in logische toolsets organisiert, die je nach Plattform aktiviert oder deaktiviert werden können.

Übergeordnete Kategorien

Zu den gängigen toolset-Namen gehören web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant und rl.¹⁰

Tools verwalten

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

Tools können außerdem während einer Sitzung über /tools disable <name> und /tools enable <name> umgeschaltet werden. Dadurch wird die Sitzung zurückgesetzt, damit das neue Toolset wirksam wird.⁹

Terminal-Backends

Das Terminal-Tool kann Befehle in sechs verschiedenen Umgebungen ausführen:¹⁰

Wechseln Sie Backends mit hermes config set terminal.backend <name> oder in config.yaml:

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

SSH-Backend (aus Sicherheitsgründen empfohlen — der Agent kann seinen eigenen Code nicht ändern):¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Docker-Backend:

terminal:
  backend: docker
  docker_image: python:3.11-slim

Container-Ressourcen (gilt für Docker, Singularity, Modal, Daytona):¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

Mit container_persistent: true bleiben installierte Pakete, Dateien und Konfigurationen sitzungsübergreifend erhalten.¹⁰

Alle Container-Backends laufen mit Sicherheits-Härtung: schreibgeschütztes Root-Dateisystem (Docker), alle Linux-Capabilities außer DAC_OVERRIDE, CHOWN und FOWNER entfernt, keine Rechteausweitung, PID-Limits (256 Prozesse), vollständige Namespace-Isolation, persistenter Arbeitsbereich über Volumes.¹⁰

Hintergrundprozesse

Das Terminal-Tool unterstützt Hintergrundausführung mit explizitem Prozessmanagement:¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

Der PTY-Modus (pty=true) ermöglicht interaktive CLI-Tools wie Codex und Claude Code.¹⁰

Sudo

Wenn ein Befehl sudo benötigt, fragt Hermes nach Ihrem Passwort (für die Sitzung zwischengespeichert). Alternativ können Sie SUDO_PASSWORD in ~/.hermes/.env setzen.¹⁰

Multi-Agent-Kanban (v0.13.0+)

v0.13.0 macht Multi-Agent-Zusammenarbeit zu einem Primitive erster Klasse: einem dauerhaften Kanban-Board, das Aufgaben, Status und Worker-Identität agentenübergreifend und über Neustarts hinweg verfolgt.¹⁸ Das Board sorgt dafür, dass ein Schwarm von Hermes-Workern Arbeit tatsächlich abschließt, statt an toten Handoffs hängenzubleiben.

Das Kanban-Board passt auf der Zielseite natürlich zu /goal (locked-target Ralph loop) und bei Spawn-Semantiken zum bestehenden delegate_task-Tool. Das Ergebnis ist ein Schwarmmuster, bei dem jeder Agent dieselbe Quelle der Wahrheit dafür teilt, was als Nächstes zu tun ist, wer daran arbeitet und was feststeckt.

Skill-System

Skills sind Wissensdokumente auf Abruf, die der Agent bei Bedarf laden kann. Sie folgen einem Muster der progressiven Offenlegung, um die Token-Nutzung zu minimieren, und sind mit dem offenen Standard agentskills.io kompatibel.¹¹

Alle Skills liegen in ~/.hermes/skills/ — dem primären Verzeichnis und der maßgeblichen Quelle. Bei einer Neuinstallation werden gebündelte Skills aus dem Repo kopiert. Über Hub installierte und vom Agent erstellte Skills landen ebenfalls hier.¹¹

Progressive Offenlegung

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

Der Agent lädt den vollständigen Skill-Inhalt nur dann, wenn er ihn tatsächlich benötigt.¹¹

Format von SKILL.md

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

Bedingte Aktivierung

Skills können sich je nach verfügbaren Tools ein- oder ausblenden. Das ist vor allem für Fallback-Skills nützlich — kostenlose oder lokale Alternativen, die nur erscheinen sollen, wenn ein Premium-Tool nicht verfügbar ist:¹¹

Beispiel: Der integrierte Skill duckduckgo-search verwendet fallback_for_toolsets: [web]. Wenn Sie FIRECRAWL_API_KEY gesetzt haben, ist das Web-toolset verfügbar und der Agent verwendet web_search — der DuckDuckGo-Skill bleibt ausgeblendet. Ohne den Schlüssel API erscheint der DuckDuckGo-Skill automatisch als Fallback.¹¹

Vom Agent verwaltete Skills

Der Agent kann über das Tool skill_manage eigene Skills erstellen, aktualisieren und löschen. Das ist das prozedurale Gedächtnis des Agents — wenn er einen nicht trivialen Workflow herausfindet, speichert er den Ansatz als Skill zur späteren Wiederverwendung.¹¹

Wann der Agent Skills erstellt:¹¹ - Nach erfolgreichem Abschluss einer komplexen Aufgabe (5+ Tool-Aufrufe) - Wenn er auf Fehler oder Sackgassen gestoßen ist und den funktionierenden Weg gefunden hat - Wenn der Benutzer seinen Ansatz korrigiert hat - Wenn er einen nicht trivialen Workflow entdeckt hat

Aktionen:¹¹

Skill Hub

Durchsuchen, suchen, installieren und verwalten Sie Skills aus Online-Registries:⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

Integrierte Hub-Quellen:¹¹

Standardmäßige GitHub taps (ohne Einrichtung durchsuchbar): openai/skills, anthropics/skills, VoltAgent/awesome-agent-skills, garrytan/gstack.¹¹

Sicherheitsprüfung

Alle über den Hub installierten Skills durchlaufen einen Sicherheitsscanner, der auf Datenexfiltration, Prompt Injection, destruktive Befehle, Supply-Chain-Signale und andere Bedrohungen prüft.¹¹

Vertrauensstufen:¹¹

--force kann nicht gefährliche Richtlinienblockaden für Community-Skills überschreiben. Es überschreibt kein dangerous-Scanurteil.¹¹

Externe Skill-Verzeichnisse

Sie können Hermes auf zusätzliche Skill-Verzeichnisse verweisen, die zusammen mit dem lokalen Verzeichnis gescannt werden:¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Pfade unterstützen ~-Expansion und die Ersetzung von Umgebungsvariablen mit ${VAR}. Externe Verzeichnisse sind schreibgeschützt — wenn der Agent einen Skill erstellt oder bearbeitet, schreibt er immer nach ~/.hermes/skills/. Lokale Priorität gewinnt, wenn an beiden Orten ein Skill-Name existiert.¹¹

Persistenter Speicher

Hermes verfügt über begrenzten, kuratierten Speicher, der sitzungsübergreifend bestehen bleibt. Der Speicher des Agenten besteht aus 2 Dateien, die beide in ~/.hermes/memories/ gespeichert werden:¹²

Beide werden beim Sitzungsstart als eingefrorener Snapshot in den System-Prompt eingefügt. Der Agent verwaltet seinen eigenen Speicher über das memory-Tool — add, replace oder remove.¹²

Muster des eingefrorenen Snapshots: Die System-Prompt-Einfügung wird einmal beim Sitzungsstart erfasst und ändert sich während der Sitzung nicht mehr. Das ist beabsichtigt — so bleibt der Prefix-Cache von LLM für bessere Leistung erhalten. Änderungen, die während einer Sitzung vorgenommen werden, werden sofort auf die Festplatte geschrieben, erscheinen aber erst in der nächsten Sitzung im System-Prompt.¹²

Was gespeichert werden sollte

Speichern Sie dies (der Agent tut das proaktiv):¹² - Benutzerpräferenzen: “I prefer TypeScript over JavaScript” → user - Umgebungsfakten: “This server runs Debian 12 with PostgreSQL 16” → memory - Korrekturen: “Don’t use sudo for Docker commands, user is in docker group” → memory - Konventionen: “Project uses tabs, 120-char line width, Google-style docstrings” → memory - Abgeschlossene Arbeit: “Migrated database from MySQL to PostgreSQL on 2026-01-15” → memory

Überspringen Sie dies:¹² - Triviale/offensichtliche Informationen - Fakten, die sich leicht erneut ermitteln lassen - Rohdaten-Dumps (zu groß für den Speicher) - Sitzungsspezifische Kurzlebigkeiten - Informationen, die bereits in Kontextdateien stehen

Sitzungssuche

Über MEMORY.md und USER.md hinaus kann der Agent mit dem session_search-Tool frühere Gespräche durchsuchen. Alle CLI- und Messaging-Sitzungen werden in SQLite (~/.hermes/state.db) mit FTS5-Volltextsuche gespeichert. Abfragen geben relevante frühere Gespräche mit Gemini Flash-Zusammenfassung zurück.¹²

Externe Speicheranbieter

Für tieferen persistenten Speicher über MEMORY.md und USER.md hinaus bringt Hermes 8 externe Speicheranbieter-Plugins mit: Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover und Supermemory.¹²

Externe Anbieter laufen zusätzlich zum integrierten Speicher (sie ersetzen ihn nie) und ergänzen Funktionen wie Wissensgraphen, semantische Suche, automatische Faktenextraktion und sitzungsübergreifende Benutzermodellierung:⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

Es kann immer nur 1 externer Anbieter aktiv sein. Der integrierte Speicher ist immer aktiv.⁶

Automatische Sitzungsfortsetzung (v0.13.0+)

v0.13.0 macht Unterbrechungen mitten in Agentenläufen überlebbar. Der gateway setzt unterbrochene Sitzungen nach einem Neustart automatisch fort; /update-Neustarts bewahren den Sitzungszustand während des Upgrades; Source-Datei-Reloads während der Entwicklung halten die aktive Sitzung am Leben, statt eine neue zu erzwingen.¹⁸ Praktischer Effekt: Lang laufende gateway-Arbeit und cron-gesteuerte Jobs setzen ihr Kontextfenster nicht mehr zurück, wenn der Prozess neu startet.

Checkpoints v2 (v0.13.0+)

Die Zustandspersistenz wird in v0.13.0 als Single-Store-Design mit echtem Pruning, Festplattenleitplanken und ohne verwaiste Shadow-Repos neu geschrieben.¹⁸ Das bisherige checkpoint-System sammelte bei lang laufenden profiles Zustand auf der Festplatte an; der v2-Store setzt eine harte Obergrenze für lokalen checkpoint-Speicher und entfernt die doppelte Buchführung, die dieses Wachstum verursacht hat. Eine benutzerseitige Konfigurationsänderung ist nicht erforderlich; der nächste checkpoint-Schreibvorgang nutzt den v2-Pfad.

Persönlichkeit & SOUL.md

SOUL.md ist die primäre Identität einer Hermes-Instanz. Sie belegt Slot #1 im System-Prompt und ersetzt die fest codierte Standardidentität.¹³

Hermes legt automatisch eine Standard-SOUL.md unter ~/.hermes/SOUL.md an (oder $HERMES_HOME/SOUL.md für benutzerdefinierte profiles). Bestehende Benutzerdateien werden nie überschrieben. Hermes lädt SOUL.md nur aus HERMES_HOME — es sucht nicht im aktuellen Arbeitsverzeichnis. Dadurch bleibt die Persönlichkeit projektübergreifend vorhersehbar.¹³

Was in SOUL.md gehört

Nutzen Sie sie für dauerhafte Vorgaben zu Stimme und Persönlichkeit:¹³ - Ton - Kommunikationsstil - Direktheitsgrad - Standardinteraktionsstil - stilistisch zu vermeidende Dinge - wie Hermes mit Unsicherheit, Widerspruch und Mehrdeutigkeit umgehen sollte

Nutzen Sie sie seltener für:¹³ - einmalige Projektanweisungen - Dateipfade - Repo-Konventionen - temporäre Workflow-Details

Diese gehören in AGENTS.md, nicht in SOUL.md.

SOUL.md vs. AGENTS.md

Das ist die wichtigste Unterscheidung im Identitätsmanagement von Hermes:¹³

SOUL.md — Identität, Ton, Stil, Kommunikationsstandards, Verhalten auf Persönlichkeitsebene.

AGENTS.md — Projektarchitektur, Coding-Konventionen, Tool-Präferenzen, repo-spezifische Workflows, Befehle, Ports, Pfade, Deployment-Notizen.

Eine nützliche Regel: Wenn es Sie überallhin begleiten soll, gehört es in SOUL.md. Wenn es zu einem Projekt gehört, gehört es in AGENTS.md.¹³

Integrierte Persönlichkeiten

Hermes bringt integrierte Persönlichkeiten mit, zu denen Sie mit /personality wechseln können:¹³

Benutzerdefinierte Persönlichkeiten in config.yaml:¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Wechseln Sie dann mit /personality codereviewer.

SOUL.md vs. /personality

SOUL.md ist die grundlegende Stimme. /personality ist eine Überlagerung auf Sitzungsebene.¹³ Halten Sie eine pragmatische Standard-SOUL.md vor und verwenden Sie dann /personality teacher für ein Tutoring-Gespräch oder /personality creative fürs Brainstorming.

Nous Tool Gateway (v0.10.0+)

Seit Hermes Agent v0.10.0 (16. April 2026) erhalten zahlende Nous Portal-Abonnenten über ihre bestehenden Portal-Zugangsdaten verwalteten Zugriff auf eine kuratierte Tool-Auswahl — ohne zusätzliche API-Schlüssel verwalten zu müssen.²¹ Die Hermes CLI selbst bleibt MIT-lizenziert und vollständig Open Source. Geändert hat sich, dass Ihre Portal-Authentifizierung jetzt mehr als nur Modellinferenz freischaltet.

Was im gateway enthalten ist

Funktionsweise

Der gateway ist pro Tool opt-in über ein neues use_gateway-Konfigurationsfeld. Wenn Sie Portal-Zugangsdaten in hermes auth haben und den gateway für ein Tool aktivieren, werden die Aufrufe dieses Tools über Portal geroutet. Andernfalls wird Ihr direkter API-Schlüssel (falls vorhanden) verwendet.

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

Runtime-Priorität: Wenn der gateway verfügbar ist und ein Tool use_gateway: true gesetzt hat, bevorzugt Hermes den gateway, selbst wenn Sie zusätzlich einen direkten API-Schlüssel konfiguriert haben. Das ist für die Abrechnung relevant — gateway-Aufrufe werden aus Ihrem Portal-Abonnement bedient, nicht aus dem Guthaben Ihres direkten API-Schlüssels.

gateway aktivieren

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

Es gibt keinen separaten Befehl hermes subscribe oder hermes login --portal. Das Abonnement wird automatisch anhand der Portal-OAuth-Zugangsdaten erkannt, die Sie bereits in hermes auth haben.

Preise und Zugriff

Preise und Tarifnamen werden auf der Nous Portal-Preisseite veröffentlicht (https://portal.nousresearch.com/pricing). Dieser Leitfaden listet keine Tarife auf, weil sie in die Verantwortung des Portal-Produkts fallen, nicht der Hermes CLI, und sich unabhängig von Hermes-Releases ändern. Registrieren Sie sich unter https://portal.nousresearch.com/ und prüfen Sie die Preisseite auf aktuelle Tarife.

Hinweis zur Einstellung

• Die Umgebungsvariable HERMES_ENABLE_NOUS_MANAGED_TOOLS wurde in v0.10.0 entfernt. Managed Tools werden jetzt über das Tool-spezifische Konfigurationsfeld use_gateway aktiviert und durch den Status Ihres Portal-Abonnements freigeschaltet.²¹

Einordnung: was dieses Release nicht ist

Die Hermes Agent CLI ist nicht hinter einem Abonnement verborgen. Das Projekt ist weiterhin MIT-lizenziert, alle Kernfunktionen (CLI, skills, Speicher, Messaging-gateway, cron, MCP, lokales Dashboard, BYOK für jeden Anbieter) funktionieren durchgängig, ohne irgendwen zu bezahlen. v0.10.0 ergänzt einen bequemeren Weg für Benutzer, die bereits für Nous Portal bezahlen — es entfernt nichts aus dem kostenlosen Weg.

Messaging Gateway

Hermes kann als dauerhaft laufender gateway-Prozess betrieben werden, der 22 Messaging-Plattformen über einen einzigen gateway-Prozess verbindet: Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat, LINE, SimpleX Chat und einen generischen Webhook-Adapter.^320171819 v0.9.0 fügte iMessage über BlueBubbles hinzu (automatische Webhook-Registrierung, Einrichtungsassistent, Absturzresilienz) sowie native WeChat-Unterstützung über iLink Bot API mit WeCom-Callback-Modus für Unternehmens-Apps.¹⁶ v0.11.0 fügte QQBot hinzu.²⁰ v0.12.0 fügte Microsoft Teams und Tencent Yuanbao hinzu.¹⁷ v0.13.0 fügte Google Chat als 20. Plattform hinzu, auf Basis derselben steckbaren Adapterarchitektur; IRC und Microsoft Teams wurden außerdem auf das neue Adaptermuster mit generischen env_enablement_fn- / cron_deliver_env_var-Plugin-Hooks migriert.¹⁸ v0.14.0 fügt LINE und SimpleX Chat hinzu und vervollständigt den Microsoft Teams-Stack durchgängig mit Graph-Auth, Webhook-Listener, Pipeline-Runtime und ausgehender Zustellung.¹⁹

Einrichtung

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

Die interaktive Einrichtung führt Sie durch die Verbindung jeder Plattform: API-Tokens, Bot-IDs, Kanalzuordnungen, Allowlists.⁶

Nachrichtenfluss

Aus den Upstream-Architekturdokumenten:³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

Jede Messaging-Plattform läuft durch dieselbe AIAgent-Konversationsschleife wie CLI. Deshalb funktionieren Slash-Befehle an beiden Stellen identisch, und deshalb kann ein in Telegram geplanter cron-Job seine Ausgabe an Discord liefern - der Plattformunterschied liegt nur am Rand.³

Benutzerautorisierung und Pairing

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

Pairing-Codes verhindern, dass beliebige Fremde mit Ihrem gateway sprechen. Ein Benutzer sendet einen Pairing-Code von seiner Messaging-Plattform; Sie genehmigen ihn mit hermes pairing approve; ab dann ist der Benutzer autorisiert.⁶

Geplante Aufgaben (cron)

Hermes hat ein erstklassiges cron-System, in dem Jobs Agentenaufgaben sind, keine Shell-Befehle. Jeder geplante Job läuft durch einen frischen AIAgent mit dem konfigurierten Prompt, optional angehängten skills, und liefert Ergebnisse an jede Plattform:³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

Oder erstellen Sie einen Job dialogisch innerhalb eines Messaging-Chats:

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

Der Agent richtet den cron-Job über seine Tools ein. Jobs bleiben in JSON bestehen und überstehen Neustarts.³

MCP-Integration

Hermes unterstützt das Model Context Protocol sowohl als Client als auch als Server:⁶

Als Client - verbinden Sie Hermes mit externen MCP-Servern, um seine Tool-Oberfläche zu erweitern:

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

Oder manuell in config.yaml:¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Als Server - stellen Sie Hermes-Konversationen anderen Agents bereit:

hermes mcp serve
hermes mcp serve -v    # Verbose

Kontextkomprimierung

Hermes komprimiert lange Konversationen automatisch, damit sie innerhalb des Kontextfensters Ihres Modells bleiben. Der Komprimierungs-Summarizer ist ein separater LLM-Aufruf - Sie können ihn auf jeden Provider oder Endpoint richten.⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve as recent tail
  protect_last_n: 20                        # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                  # "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                    # Custom OpenAI-compatible endpoint

Provider-Optionen:⁴

summary_model muss eine Kontextlänge unterstützen, die mindestens so groß ist wie die Ihres Hauptmodells, da es für die Komprimierung den vollständigen mittleren Abschnitt der Konversation erhält.⁴

Warnungen bei Budgetdruck

Wenn der Agent an einer komplexen Aufgabe mit vielen Tool-Aufrufen arbeitet, kann er sein Iterationsbudget (Standard: 90 Durchläufe) verbrauchen, ohne es zu merken. Budgetdruck warnt das Modell automatisch:⁴

Stream-Timeouts

Die LLM-Streaming-Verbindung hat zwei Timeout-Ebenen, die sich für lokale Provider (localhost, LAN-IPs) automatisch anpassen:⁴

Der Socket-Lese-Timeout wird für lokale Endpoints auf 30 Minuten erhöht, weil lokale LLMs bei großen Kontexten mehrere Minuten für Prefill benötigen können, bevor sie das erste Token erzeugen.⁴

Lokales Web-Dashboard (v0.9.0+)

Ein browserbasiertes Dashboard zur lokalen Verwaltung Ihres Hermes Agent. Konfigurieren Sie Einstellungen, überwachen Sie Sitzungen, durchsuchen Sie skills und verwalten Sie Ihr gateway, ohne Konfigurationsdateien oder das Terminal anzufassen.¹⁶ Starten Sie es mit hermes dashboard. Dies ist der einfachste Onboarding-Pfad für neue Benutzer, die eine GUI bevorzugen.

Hintergrundprozessüberwachung (v0.9.0+)

Mit watch_patterns können Sie Muster festlegen, die in der Ausgabe von Hintergrundprozessen überwacht werden, und sich in Echtzeit benachrichtigen lassen, wenn sie übereinstimmen.¹⁶ Überwachen Sie Fehler, warten Sie auf bestimmte Ereignisse („listening on port“) oder beobachten Sie Build-Logs - ganz ohne Polling. Zusammen mit notify_on_complete aus v0.8.0 (das über den Abschluss von Hintergrundaufgaben benachrichtigt) verfügt Hermes nun über eine vollständige Observability-Ebene für Hintergrundprozesse.¹⁵

Steckbare Context Engine (v0.9.0+)

Kontextverwaltung ist jetzt über hermes plugins ein steckbarer Slot. Tauschen Sie benutzerdefinierte context engines ein, die steuern, was der Agent in jedem Durchlauf sieht - Filterung, Zusammenfassung oder domänenspezifische Kontextinjektion.¹⁶ Dadurch wird die Kontextstrategie von der Kernschleife des Agents entkoppelt, sodass Kontextanpassungen pro Projekt oder Domäne möglich sind.

Backup und Wiederherstellung (v0.9.0+)

hermes backup erstellt ein vollständiges Archiv Ihrer Konfiguration, Sitzungen, skills und memory. hermes import stellt aus einem Backup-Archiv wieder her.¹⁶ Nutzen Sie dies, um zwischen Rechnern zu migrieren, Snapshots vor größeren Änderungen zu erstellen oder eine bekanntermaßen funktionierende Konfiguration mit Teammitgliedern zu teilen.

Termux- / Android-Unterstützung (v0.9.0+)

Hermes läuft nativ auf Android über Termux. Angepasste Installationspfade, TUI-Optimierungen für mobile Bildschirme, Unterstützung für Voice-Backends und der /image-Befehl funktionieren direkt auf dem Gerät.¹⁶

Sicherheits-Hardening (v0.13.0+)

v0.13.0 hat 8 P0-Sicherheitsprobleme geschlossen und eine Standardeinstellung zugunsten des Benutzers geändert.¹⁸ v0.14.0 legt mit weiteren 12 P0- und 50 P1-Schließungen nach, darunter Härtung gegen sudo-Brute-Force / sudo-stdin, Korrekturen für Umgehungen gefährlicher Befehle, Bereinigung von Tool-Fehlern vor erneuter Model-Einspeisung, dashboard plugin API auth, skills-hub SSRF-Abdeckung und Supply-Chain-Advisory-Scans während der Installation.¹⁹

Wenn Sie eine Hermes-Bereitstellung betreiben, behandeln Sie v0.13.0 und v0.14.0 als sicherheitsrelevante Upgrades, nicht nur als Funktionsupdates. v0.13.0 schließt den Discord Cross-Guild-Bypass und zwei TOCTOU-Fenster; v0.14.0 ergänzt eine weitere Härtungsrunde für sudo-Handling, erneute Tool-Error-Einspeisung, plugin APIs, skills-hub SSRF und Dependency-Advisories.

Architektur für Praktiker

Dieser Abschnitt richtet sich an Personen, die verstehen möchten, was unter der Haube passiert, damit sie debuggen, erweitern oder Performance einschätzen können. Er ist eine Synthese der Upstream-Architekturdokumentation.³

Einstiegspunkte → AIAgent

Jeder Einstiegspunkt in Hermes ruft letztlich AIAgent.run_conversation() auf:

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

Diagramm adaptiert aus der Upstream-Architekturdokumentation.³

„47 Tools / 20 Toolsets“ gegenüber „28 Tools“ in Ihrem Banner. Die Zählung „47 Tools“ ist die gesamte Tool-Registry des Upstream-Repositorys, also jedes Tool, mit dessen Quellcode Hermes ausgeliefert wird, über alle toolsets hinweg. Ihr tatsächlich laufendes CLI zeigt in seinem Startbanner eine kleinere Zahl an (die Installation, gegen die ich diesen Guide geprüft habe, meldet 28 tools / 89 skills). Das ist kein Bug. Viele toolsets sind opt-in und müssen in config.yaml unter toolsets: ausdrücklich aktiviert werden, etwa Messaging-Plattform-Adapter, Browser-Automation, schwerere Scraping-Tools usw. Die Registry-Gesamtzahl bedeutet „was verfügbar ist“; die Banner-Zahl bedeutet „was in Ihrem aktuellen profile aktiviert ist“. Prüfen Sie mit hermes tools --list, welche toolsets aktiv sind, und aktivieren oder deaktivieren Sie einzelne toolsets mit dem toolsets:-Block in ~/.hermes/config.yaml (oder mit /tools list / /tools enable <name> / /tools disable <name> innerhalb einer laufenden Sitzung; das Entfernen eines Tools löst einen Sitzungs-Reset aus, damit der Agent sein Tool-Manifest neu aufbaut).

Die drei API-Modi

Hermes abstrahiert Provider-Unterschiede in drei API-Modi, die zur Laufzeit automatisch ausgewählt werden:³

Der runtime_provider.py-Resolver ordnet (provider, model)-Tupel für mehr als 18 Provider (api_mode, api_key, base_url) zu und verarbeitet dabei OAuth-Flows, Credential-Pools und Alias-Auflösung.³

Datenfluss durch eine CLI-Sitzung

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

Von der Upstream-Architekturseite.³

Reihenfolge der Prompt-Zusammensetzung

Der Prompt-Stack umfasst:¹³

1. SOUL.md (Agent-Identität oder integrierter Fallback, falls nicht verfügbar)
2. Tool-bewusste Verhaltensanweisungen
3. Memory-/Benutzerkontext (MEMORY.md, USER.md)
4. Skills-Anweisungen
5. Kontextdateien (AGENTS.md, .cursorrules)
6. Zeitstempel
7. Plattformspezifische Formatierungshinweise
8. Optionale System-Prompt-Overlays wie /personality

SOUL.md ist das Fundament; alles andere baut darauf auf.¹³

Sitzungsspeicher

SQLite-basierter Sitzungsspeicher mit FTS5-Volltextsuche. Sitzungen verfügen über Lineage-Tracking (Parent/Child über Komprimierungen hinweg), plattformbezogene Isolation und atomare Schreibvorgänge mit Behandlung von Contention.³

Plugin-System

Drei Discovery-Quellen: ~/.hermes/plugins/ (Benutzer), .hermes/plugins/ (Projekt) und pip entry points. Plugins registrieren Tools, Hooks und CLI-Befehle über einen Kontext API. Memory-Provider sind ein spezialisierter Plugin-Typ unter plugins/memory/.³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

Designprinzipien

Von der Upstream-Architekturseite:³

Migration von OpenClaw

Hermes Agent ist der Nachfolger von OpenClaw. Wenn Sie von einer bestehenden OpenClaw-Installation migrieren:⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate liest standardmäßig aus ~/.openclaw (erkennt außerdem automatisch Legacy-Verzeichnisse ~/.clawdbot und ~/.moldbot) und schreibt nach ~/.hermes.⁶

Direkt importiert (30+ Kategorien): SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills aus 4 Quellverzeichnissen, Standardmodell, benutzerdefinierte Provider, MCP-Server, Messaging-Plattform-Tokens und Allowlists (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), Agent-Standardeinstellungen (reasoning effort, Komprimierung, menschliche Verzögerung, Zeitzone, sandbox), Sitzungs-Reset-Richtlinien, approval rules, TTS-config, Browser-Einstellungen, Tool-Einstellungen, exec timeout, Befehls-Allowlist, gateway-config und API-Schlüssel aus 3 Quellen.⁶

Für manuelle Prüfung archiviert: cron-Jobs, Plugins, Hooks/Webhooks, Memory-Backend (QMD), skills registry config, UI/Identität, Logging, Multi-Agent-Setup, Kanalbindungen, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

Die Auflösung von API-Schlüsseln prüft drei Quellen in Prioritätsreihenfolge: config-Werte → ~/.openclaw/.env → auth-profiles.json.⁶

Fehlerbehebung

“API key not set”

Führen Sie hermes model aus, um Ihren Provider interaktiv zu konfigurieren, oder hermes config set OPENROUTER_API_KEY your_key. Der Befehl hermes doctor zeigt Ihnen genau, welche Schlüssel fehlen.⁷

“Context limit: 2048 tokens” beim Start (lokale Modelle)

Hermes erkennt die Kontextlänge automatisch über den /v1/models-Endpunkt Ihres Servers, viele lokale Server melden jedoch niedrige Standardwerte. Setzen Sie sie explizit in config.yaml:²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

Tool-Aufrufe erscheinen als Text statt ausgeführt zu werden

Auf Ihrem Server ist Tool Calling nicht aktiviert, oder das Modell unterstützt es nicht über die Implementierung des Servers.²

Antworten werden mitten im Satz abgeschnitten

Zwei mögliche Ursachen:²

1. Niedrige Ausgabengrenze (max_tokens) auf dem Server — SGLang verwendet standardmäßig 128 Tokens pro Antwort. Setzen Sie --default-max-tokens auf dem Server oder konfigurieren Sie model.max_tokens in config.yaml.
2. Kontext erschöpft — Das Modell hat sein Kontextfenster gefüllt. Erhöhen Sie model.context_length oder aktivieren Sie die Kontextkomprimierung in Hermes.

“Connection refused” von WSL2 zu einem in Windows gehosteten Modellserver

WSL2 verwendet einen virtuellen Netzwerkadapter mit eigenem Subnetz — localhost innerhalb von WSL2 verweist auf die Linux-VM, nicht auf den Windows-Host. Zwei Möglichkeiten:²

Mirrored Networking (Windows 11 22H2+): Bearbeiten Sie %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Anschließend wsl --shutdown und neu starten. localhost funktioniert nun in beide Richtungen.

Host-IP als Fallback (ältere Windows-Versionen): Ermitteln Sie die Windows-Host-IP innerhalb von WSL2 und verwenden Sie sie anstelle von localhost:

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

Außerdem muss der Modellserver an 0.0.0.0 gebunden sein, nicht an 127.0.0.1 — setzen Sie OLLAMA_HOST=0.0.0.0 für Ollama, fügen Sie --host 0.0.0.0 für llama-server/SGLang hinzu, oder aktivieren Sie “Serve on Network” in LM Studio.²

Wo befindet sich was?

hermes status und hermes dump sind hier Ihre Freunde. hermes logs list zeigt alle Logdateien mit Größen an. hermes config path gibt den Speicherort der Konfigurationsdatei aus. hermes config env-path gibt den Speicherort der .env-Datei aus.⁶

FAQ

Was ist der Unterschied zwischen Hermes Agent und Claude Code?

Claude Code ist die offizielle CLI von Anthropic und auf Anthropic-Modelle festgelegt. Hermes Agent ist ein Open-Source-Agent-Framework von Nous Research, das mit jedem OpenAI-kompatiblen Provider funktioniert — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google oder Ihrem eigenen selbst gehosteten Endpunkt.¹² Hermes liefert zudem ein Messaging-Gateway für Telegram/Discord/Slack/WhatsApp/Signal mit, das Claude Code nicht hat.

Kann ich Hermes mit einem Anthropic-API-Schlüssel verwenden?

Ja. Auf drei Wegen:²

1. Setzen Sie ANTHROPIC_API_KEY in ~/.hermes/.env und führen Sie hermes chat --provider anthropic --model claude-sonnet-4-6 aus
2. Führen Sie hermes model aus und wählen Sie Anthropic — Hermes verwendet den Credential Store von Claude Code, sofern verfügbar
3. Setzen Sie ein manuelles ANTHROPIC_TOKEN (Setup-Token oder OAuth-Token) als Fallback

Option 2 ist vorzuziehen, wenn Sie Claude Code bereits auf demselben Rechner verwenden — sie hält erneuerbare Claude-Anmeldedaten erneuerbar.

Wie wechsle ich den Provider, ohne meine Konversation zu verlieren?

Verwenden Sie /model provider:model innerhalb einer Sitzung. Konversationsverlauf, Memory und Skills werden alle übernommen:⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

Ich habe Anthropic konfiguriert, aber Vision/Web/Komprimierung funktionieren nicht

Sie geraten an den Fallback für das Hilfsmodell. Vision, Web-Zusammenfassung, Komprimierung und andere Nebenaufgaben verwenden ein separates Hilfs-LLM — standardmäßig Gemini Flash über automatische Erkennung (OpenRouter → Nous → Codex). Wenn keiner davon konfiguriert ist und Sie nur Anthropic eingerichtet haben, verschlechtern sich diese Funktionen stillschweigend.⁴

Lösung: Fügen Sie entweder einen OPENROUTER_API_KEY für Hilfsaufgaben hinzu oder konfigurieren Sie die Hilfs-Slots so, dass sie Ihren Hauptprovider verwenden. Beachten Sie, dass die Kontextkomprimierung in einem eigenen Top-Level-compression:-Block lebt und summary_provider annimmt, nicht auxiliary.compression.provider — der auxiliary.compression-Slot bietet nur ein timeout. Vollständige Lösung:

auxiliary:
  vision:      { provider: "main" }
  web_extract: { provider: "main" }

compression:
  summary_provider: "main"

Was ist der Unterschied zwischen SOUL.md und AGENTS.md?

SOUL.md ist die Identität Ihres Agents — Tonfall, Stil, Kommunikationsvoreinstellungen. Sie liegt in ~/.hermes/SOUL.md und folgt Ihnen überallhin. AGENTS.md ist projektspezifisch — Architektur, Konventionen, Befehle, Pfade — und liegt in Ihrem Projektverzeichnis.¹³ Wenn es Sie überallhin begleiten soll, SOUL.md. Wenn es zu einem Projekt gehört, AGENTS.md.

Wie führe ich mehrere Hermes-Instanzen nebeneinander aus?

Über Profile. Jedes Profil erhält sein eigenes HERMES_HOME, eigene Konfiguration, Memory, Sitzungen und Gateway-PID:⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

Unterstützt Hermes lokale LLMs?

Ja, über den Pfad für benutzerdefinierte Endpunkte. Hermes funktioniert mit jedem OpenAI-kompatiblen Server: Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan oder Ihrem eigenen.² Siehe Custom & Self-Hosted Endpoints für die Einrichtung pro Server.

Warum zeigt mein Start-Banner weniger Tools an, als laut Anleitung in Hermes enthalten sind?

Die Anleitung nennt 47 Tools / 20 Toolsets aus dem Upstream-Architektur-Registry — das ist die Gesamtzahl der Tools, für die Hermes Quellcode über alle Toolsets hinweg mitliefert. Ihre laufende Installation zeigt im Banner eine kleinere Zahl an (die Referenzinstallation für diese Anleitung meldet 28 Tools), weil Hermes beim Start nur die Standard-Toolsets aktiviert. Viele Toolsets sind opt-in: Messaging-Gateway-Adapter, Browser-Automatisierung, schwerere Scraping-Stacks und mehrere spezialisierte Integrationen müssen explizit unter toolsets: in ~/.hermes/config.yaml aufgeführt werden, bevor sie geladen werden. Registry-Gesamtzahl = “was verfügbar ist, wenn Sie es aktivieren.” Banner-Gesamtzahl = “was Ihr aktuelles Profil tatsächlich geladen hat.” Verwenden Sie hermes tools --list, um zu sehen, welche Toolsets aktiv sind und welche zwar verfügbar, aber deaktiviert sind. Schalten Sie einzelne Toolsets zur Laufzeit mit /tools enable <name> und /tools disable <name> um (Deaktivieren löst einen Sitzungs-Reset aus, damit der Agent sein Tool-Manifest mit der neuen Form neu aufbaut).

Wie geht Hermes mit Modell-Fallback um, wenn mein primärer Provider ausfällt?

Konfigurieren Sie einen fallback_model-Block in config.yaml:²

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

Wenn der primäre Provider ausfällt (Rate-Limit, Serverfehler, Authentifizierungsfehler), wechselt Hermes mitten in der Sitzung auf den Fallback, ohne den Konversationsverlauf zu verlieren. Wird höchstens einmal pro Sitzung ausgelöst.

Kann der Agent seine eigenen Skills im Lauf der Zeit verbessern?

Ja — das ist der “selbstverbessernde” Teil von Hermes Agent. Der Agent kann Skills über das Tool skill_manage erstellen, aktualisieren und löschen. Sobald er einen nicht trivialen Workflow herausfindet, speichert er den Ansatz als Skill zur künftigen Wiederverwendung.¹¹ Der Agent erstellt Skills nach komplexen Aufgaben (5+ Tool-Aufrufe), wenn er auf Fehler stößt und den funktionierenden Pfad findet, wenn Sie seinen Ansatz korrigieren, oder wenn er einen nicht trivialen Workflow entdeckt.

Gibt es eine IDE-Integration?

Ja — Hermes kann als ACP (Agent Client Protocol)-Server für VS Code, Zed und JetBrains laufen:⁶

pip install -e '.[acp]'
hermes acp

Änderungsprotokoll

Referenzen