Hermes Agent: Die Praktiker-Referenz (2026)

TL;DR: Hermes Agent ist ein Open-Source-Self-Improving-AI-Agent von Nous Research. Er läuft als CLI und als Multi-Plattform-Messaging-Gateway, speichert eine dauerhafte Identität sowie persistenten Speicher auf der Festplatte, aggregiert Skills, die sich mit der Nutzung verbessern, und funktioniert mit jedem OpenAI-kompatiblen LLM-Provider — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Alibaba, Hugging Face, Google oder Ihrem eigenen selbst gehosteten Endpoint.¹² Die größte Hürde für die meisten neuen Benutzer ist die Provider-Authentifizierung: Hermes unterstützt rund 19 erstklassige Provider sowie benutzerdefinierte Endpoints und drei verschiedene Auth-Pfade (API-Schlüssel in .env, OAuth via hermes model oder benutzerdefinierter Endpoint in config.yaml). Das Auth-Modell sollten Sie zuerst verstehen — alles andere ergibt sich daraus, welcher Provider aufgelöst wird.

Hermes Agent arbeitet als vollwertige Agent-Runtime, nicht als Chat-Wrapper. Er liest Ihr Dateisystem, führt Befehle in Sandbox-Backends aus, scrapt das Web, spawnt Subagenten, führt geplante Cron-Jobs aus, kommuniziert mit Telegram/Discord/Slack/WhatsApp/Signal/E-Mail über einen einzigen Gateway-Prozess und erstellt aus Erfahrung eigene Skills.¹ Die CLI ist ein Terminal-UI, das auf einem Conversation Loop in run_agent.py aufbaut; das Gateway ist ein langlaufender Prozess, der Nachrichten von Messaging-Plattformen durch denselben Conversation Loop routet.³

Der Unterschied zwischen gelegentlicher und expertenhafter Hermes-Nutzung liegt in fünf Systemen. Beherrschen Sie diese, wird Hermes zum Force Multiplier:

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- und Toolset-System: Was der Agent tun kann, pro Plattform gesteuert
4. Skills-System: Prozedurales Gedächtnis, das der Agent erstellt und weiterentwickelt
5. Gateway + Cron + Profile: Hermes dort betreiben, wo Sie leben — nicht nur dort, wo Sie sind

Wichtigste Erkenntnisse

• Provider-Auth umfasst drei Pfade, nicht einen. API-Schlüssel in .env, OAuth via hermes model/hermes auth oder benutzerdefinierter Endpoint in config.yaml. Wählen Sie den Pfad, der zu Ihrem Provider passt — nicht den, der vertraut wirkt.
• Provider zu wechseln ist ein einziger Befehl. hermes model führt Sie interaktiv durch jeden unterstützten Provider, einschließlich OAuth-Logins, und /model provider:model wechselt mitten in der Session, ohne den Verlauf zu verlieren.²
• Zwei Dateien bilden die benutzerseitig editierbare Konfigurationsoberfläche. ~/.hermes/config.yaml enthält Einstellungen und ~/.hermes/.env enthält Secrets. auth.json, SOUL.md, MEMORY.md und skills/ werden direkt von Hermes verwaltet — SOUL.md können Sie von Hand bearbeiten, der Rest wird vom Agent selbst angefasst.⁴
• Hermes ist der Nachfolger von OpenClaw. Bei einer Migration importiert hermes claw migrate automatisch über 30 Zustandskategorien.⁵
• Die Servicequalität hängt von Ihrem Auxiliary-Modell ab. Vision, Web-Zusammenfassung, Kompression und Memory-Flush nutzen alle ein separates Auxiliary-LLM. Standardmäßig ist dies Gemini Flash via Auto-Detection (OpenRouter → Nous → Codex) — wenn keiner davon konfiguriert ist, verschlechtern sich diese Funktionen stillschweigend, bis Sie die Auxiliary-Slots auf Ihren Hauptprovider umlenken.⁴

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

Wählen Sie Ihren Pfad

Wie Hermes funktioniert: Das mentale Modell

Hermes basiert auf einer einzigen Konversationsschleife, 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, wobei folgende Schritte durchlaufen werden:

1. Aufbau des System-Prompts aus SOUL.md, MEMORY.md, USER.md, Skills, Kontextdateien und Tool-Anweisungen über prompt_builder.py³
2. Auflösung des Runtime-Providers über runtime_provider.py — in diesem Schritt werden Authentifizierung, Basis-URL und API-Modus bestimmt³
3. Aufruf des Providers in einem von drei API-Modi: chat_completions, codex_responses oder anthropic_messages³
4. Weiterleitung aller zurückgegebenen Tool-Aufrufe über model_tools.py und die zentrale Tool-Registry (tools/registry.py)³
5. Wiederholung der Schleife, bis das Modell eine endgültige Antwort liefert; anschließend wird die Sitzung in SQLite mit FTS5 persistiert³

Dieses Verständnis der Schleife ist entscheidend, da sich jede Funktion — Personalities, Memory, Skills, Komprimierung, Fallback — an eine dieser Stufen anhängt. Wenn Sie sich bei einem Konfigurationsschlüssel fragen, was er bewirkt, lautet die Antwort in der Regel: „Er ist ein Stellrad an Stufe 1, 2, 3 oder 4 der obigen Schleife.”

Plattformunabhängiger Kern. Eine einzige AIAgent-Klasse bedient CLI, Gateway, ACP, Batch und API-Server. Plattformspezifische Unterschiede befinden sich im Einstiegspunkt, nicht im Agenten selbst.³ Deshalb funktionieren dieselben Slash-Befehle sowohl im Terminal als auch in Telegram — sie werden über eine gemeinsame COMMAND_REGISTRY in hermes_cli/commands.py verteilt.⁶

Die Verzeichnisstruktur 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 oben genannten Dateien hat eine spezifische Aufgabe; keine davon überschneidet sich mit einer anderen. Wenn Sie wissen möchten, „wo speichert Hermes X”, ist es eine dieser Dateien.

Installation

Das Einzeiler-Installationsskript ist der Weg für 95 % aller Benutzer. Es kümmert sich um Python, uv, Node.js, ripgrep, ffmpeg, das Repository-Klonen, die virtuelle Umgebung und den globalen hermes-Befehl.⁷

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

Funktioniert unter Linux, macOS, WSL2 und Android/Termux (das Installationsskript erkennt Termux automatisch und wechselt zu einem getesteten Android-Bundle).⁷ Natives Windows wird nicht unterstützt — installieren Sie WSL2 und führen Sie den obigen Befehl von dort aus.⁷

Nach Abschluss der Installation:

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

Die einzige Voraussetzung ist git. Das Installationsskript stellt automatisch Python 3.11 ü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 zeigt Ihnen genau, was fehlt und wie Sie es beheben können.⁷ hermes dump ist der Diagnosebefehl, den Sie in ein GitHub-Issue oder einen Discord-Thread einfügen sollten, wenn Sie um Hilfe bitten — eine Klartextzusammenfassung Ihres gesamten Setups mit geschwärzten Geheimnissen.⁸

Manuelle Installation

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

Der Termux-Installationsbefehl unterscheidet sich — er verwendet pip mit einer Constraints-Datei, nicht uv pip:

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

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

Authentifizierung & Provider

Hermes unterstützt rund 19 erstklassige Provider sowie benutzerdefinierte Endpunkte und drei verschiedene Authentifizierungspfade. Hier finden Sie die gesamte Auth-Oberfläche, nach Pfad geordnet, damit Sie den passenden für Ihre Situation finden.

Die drei Authentifizierungspfade

Jeder Provider in Hermes lässt sich einem von drei Authentifizierungsmustern zuordnen:

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

Pfad 2 — OAuth über hermes model oder hermes auth. Startet einen Device-Code-Flow, öffnet einen Browser und speichert die Anmeldedaten in ~/.hermes/auth.json (kann auch vorhandene Anmeldedaten 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. Einmalig über hermes model → Custom endpoint konfiguriert und anschließend in config.yaml persistiert.²

Die vollständige Provider-Matrix

Dies ist die komplette Liste der erstklassigen Provider mit dem genauen Einrichtungsablauf für jeden einzelnen.²

Anthropic: Drei Authentifizierungsmethoden

Anthropic erhält einen eigenen Abschnitt, weil Hermes drei verschiedene Wege in Claude unterstützt — und die Wahl des richtigen Wegs ist entscheidend. 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 wählen, bevorzugt Hermes den Anmeldedatenspeicher von Claude Code, statt das Token in ~/.hermes/.env zu kopieren. Damit bleiben aktualisierbare Claude-Anmeldedaten aktualisierbar.² Falls Sie Claude Code ohnehin auf derselben Maschine nutzen, ist dies der sauberste Weg.

Um Anthropic dauerhaft in config.yaml festzulegen:

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

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

GitHub Copilot: Zwei Modi

Copilot wird in zwei Modi unterstützt: direkte Copilot-API (empfohlen) und Copilot ACP (das die lokale Copilot-CLI als Subprozess startet).²

# 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. Fallback gh auth token CLI 5. OAuth-Device-Code-Login über hermes model

Der Token-Typ ist entscheidend. Die Copilot-API unterstützt keine klassischen Personal Access Tokens (ghp_*). Unterstützt werden OAuth-Tokens (gho_*), Fine-Grained PATs (github_pat_* mit der Berechtigung Copilot Requests) und GitHub-App-Tokens (ghu_*). Liefert gh auth token ein ghp_*-Token zurück, authentifizieren Sie sich stattdessen über hermes model per OAuth.²

Chinesische KI-Provider (erstklassige Unterstützung)

Hermes verfügt über integrierte Unterstützung für z.ai/GLM, Kimi/Moonshot, MiniMax (globale und chinesische Endpunkte) sowie 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 lassen sich über die Umgebungsvariablen GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL oder DASHSCOPE_BASE_URL überschreiben.²

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

xAI (Grok) aktiviert Prompt-Caching automatisch. Enthält die Basis-URL x.ai, sendet Hermes bei jeder Anfrage den Header x-grok-conv-id, um innerhalb einer Konversationssitzung an denselben Server zu routen und zwischengespeicherte System-Prompts und Verlauf wiederzuverwenden.² Automatisch; keine Konfiguration erforderlich.

Der Befehl hermes auth

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

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

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

Benutzerdefinierte und selbst gehostete Endpunkte

Hermes funktioniert mit jedem OpenAI-kompatiblen API-Endpunkt. Implementiert ein Server /v1/chat/completions, 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 persistieren in config.yaml, das die alleinige Quelle der Wahrheit für Hauptmodell, Provider und Basis-URL ist.² Die Legacy-Umgebungsvariablen OPENAI_BASE_URL und LLM_MODEL werden nicht mehr für die Konfiguration des Hauptmodells gelesen — verwenden Sie hermes model oder bearbeiten Sie config.yaml direkt.² (OPENAI_BASE_URL + OPENAI_API_KEY werden weiterhin als Fallback für den Routing-Pfad des Hilfs-provider: "main" berücksichtigt; löschen Sie sie also nicht blind, wenn Sie sie dort einsetzen.)⁴

Benutzerdefinierte Endpunkte mitten in der 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 (ohne Modellnamen) fragt die /v1/models-API Ihres Endpunkts ab und wählt automatisch das Modell aus, sofern genau eines geladen ist — nützlich für lokale Server, die ein einzelnes Modell betreiben.²

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 zentralen Befehle, die Sie tatsächlich ausführen werden. Jeder ist darauf ausgelegt, einen funktionierenden Endpunkt zu erzeugen, auf den Hermes verweisen kann.²

Ollama — der einfachste lokale Weg, ohne 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

Wichtige Ollama-Falle: Ollama verwendet standardmäßig sehr niedrige Kontextlängen (4.096 Tokens bei unter 24 GB 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 den Einsatz als Agent setzen Sie mindestens 16k–32k.

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 reiner Text zurück.²

SGLang — schnelles Serving mit RadixAttention für KV-Cache-Wiederverwendung:

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-Falle: 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, falls 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 dieses Flag ignoriert llama-server den tools-Parameter komplett, und das Modell versucht, Tools aufzurufen, indem es JSON in seinen Antworttext schreibt — was Hermes nicht als tatsächliche Tool-Aufrufe interpretieren kann.²

LM Studio — Desktop-App mit GUI:

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

Wichtige LM-Studio-Falle: LM Studio liest die Kontextlänge aus den Modell-Metadaten, viele GGUF-Modelle melden jedoch Standardwerte von 2048 oder 4096. Setzen Sie die Kontextlänge stets ausdrücklich in den LM-Studio-Modelleinstellungen — klicken Sie auf das Zahnradsymbol neben der Modellauswahl, setzen Sie „Context Length” auf mindestens 16384 (idealerweise 32768) und laden Sie das Modell neu.²

Benannte benutzerdefinierte Provider

Wenn Sie mit mehreren benutzerdefinierten Endpunkten arbeiten (etwa einem lokalen Entwicklungsserver und einem entfernten GPU-Server), definieren Sie diese als benannte benutzerdefinierte Provider 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

Anschließend wechseln Sie mitten in der Sitzung mit der Tripel-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 Provider auch im interaktiven Menü von hermes model auswählen.²

Pluggable-Provider-Architektur (v0.13.0+)

v0.13.0 liefert eine ProviderProfile-ABC plus ein Verzeichnis plugins/model-providers/ aus, sodass Inferenz-Provider von Drittanbietern ohne Kernanpassungen integriert werden können.¹⁸ Spricht ein Provider einen OpenAI-, Anthropic- oder Codex-kompatiblen API-Modus, können Sie eine ProviderProfile-Subklasse implementieren, die den Auth-Pfad, die Basis-URL, den Modellkatalog und die Caching-Header deklariert; Hermes löst sie über denselben runtime_provider.py-Pfad auf, den auch die integrierten Provider nutzen. Dies ist die architektonische Änderung hinter der Provider-Erweiterung in v0.13.0: Statt den Kerncode zu bearbeiten, um einen Provider hinzuzufügen, liefern Sie ein Plugin aus.

Erkennung der Kontextlänge

Zwei Einstellungen werden laut Upstream-Dokumentation regelmäßig 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 diesen Wert, um zu entscheiden, wann der Verlauf komprimiert werden soll.
• model.max_tokens — die Ausgabe-Obergrenze (maximale Anzahl Tokens, die das Modell in einer einzelnen Antwort generieren darf). Hat nichts mit der Verlaufslänge zu tun.

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

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: Config-Override → benutzerdefinierter Provider pro Modell → persistenter Cache → Endpunkt /models → Anthropic /v1/models → OpenRouter-API → Nous Portal → models.dev (community-gepflegte Registry für 3800+ Modelle) → Fallback-Standardwerte (128K).² Das System ist provider-bewusst, sodass dasselbe Modell je nach Anbieter unterschiedliche Kontextgrenzen aufweisen kann (z. B. ist claude-opus-4.6 direkt bei Anthropic 1M groß, bei GitHub Copilot dagegen 128K).²

Provider-Rotation & Fallback

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

Fallback-Modell. Konfigurieren Sie ein Backup-provider:model, auf das Hermes automatisch umschaltet, wenn Ihr Hauptmodell ausfällt (Rate-Limits, Serverfehler, Auth-Fehler):²

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 mitten in der Sitzung aus, ohne Ihre Konversation zu verlieren. Er löst höchstens einmal pro Sitzung aus.² Unterstützte Provider für den 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 setzt schlanke „Hilfsmodelle” für Nebenaufgaben ein: Bildanalyse, Zusammenfassung von Webseiten, Analyse von Browser-Screenshots, Klassifizierung der Freigabe gefährlicher Befehle, Kontextkompression, Zusammenfassung der Sitzungssuche, Skill-Matching, MCP-Tool-Dispatch und Memory-Flush.⁴ Standardmäßig nutzen diese Gemini Flash über automatische 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 „den Provider verwenden, den auch mein Hauptagent nutzt” — gültig ausschließlich in den Konfigurationen auxiliary:, compression: und fallback_model:. Sie ist nicht für Ihre Top-Level-Einstellung model.provider gültig. Verwenden Sie einen benutzerdefinierten OpenAI-kompatiblen Endpunkt als Hauptmodell, setzen Sie provider: custom in Ihrem model:-Abschnitt.⁴

Warum das wichtig ist: Falls Sie nur Anthropic OAuth konfiguriert haben (kein OpenRouter-Schlüssel), werden Bildanalyse, Web-Zusammenfassung und Kompression beeinträchtigt oder schlagen fehl, weil die standardmäßige Hilfs-Fallback-Kette zuerst OpenRouter versucht. Ergänzen Sie einen OPENROUTER_API_KEY für Hilfsaufgaben oder konfigurieren Sie jeden Hilfsslot so um, dass er Ihren Haupt-Provider nutzt:

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

Dies ist die mit Abstand häufigste „Meine Funktionen funktionieren stillschweigend nicht”-Falle für neue Hermes-Benutzer.

Konfigurationssystem

Hermes verfügt über ein mehrschichtiges Konfigurationssystem. Das Verständnis der Vorrangregeln ist entscheidend, da höhere Schichten niedrigere überschreiben und eine der Schichten eine globale Provider-Registry ist, die in config.yaml nicht sichtbar ist.

Aufbau der Konfigurationsdateien

Gemäß der offiziellen Dokumentation bilden die folgenden 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, hat config.yaml bei nicht-geheimen Einstellungen Vorrang.⁴ Die Regel lautet: - Geheimnisse (API-Schlüssel, Bot-Tokens, Passwörter) → .env - Alles andere (Modell, Terminal-Backend, Komprimierungseinstellungen, Memory-Limits, Toolsets) → config.yaml

Geheimnisse können aus config.yaml mittels Shell-artiger 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 in Ihrer Datei noch fehlen.⁶

Vorrang der Konfiguration

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

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

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

Lokalisierung (v0.13.0+)

v0.13.0 fügt 7 Sprachversionen für CLI- und Gateway-Meldungen hinzu: Chinesisch (Vereinfacht), Japanisch, Deutsch, Spanisch, Französisch, Ukrainisch und Türkisch.¹⁸ Die Dokumentation ist derzeit nur in zh-Hans lokalisiert. Die Sprache wird aus den Umgebungsvariablen LC_ALL / LANG oder einem expliziten locale:-Schlüssel in config.yaml ermittelt. Englisch bleibt die Standardsprache und die Quelle der Wahrheit für jede Zeichenkette, die noch nicht von einer Übersetzung abgedeckt ist.

Profile — Mehrere isolierte Hermes-Instanzen

Profile ermöglichen mehrere isolierte Hermes-Instanzen, jede mit eigener Konfiguration, eigenen Sessions, Skills, Memory und Gateway-PID. So können Sie „Arbeits-Hermes” und „Privat-Hermes” parallel 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 Profil erhält sein eigenes HERMES_HOME (standardmäßig ~/.hermes-<name>/), sodass mehrere Profile das Gateway gleichzeitig betreiben können, ohne sich gegenseitig zu beeinträchtigen.⁶³

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 ausgeführt (CLI oder Messaging-Plattform). Sie werden über ein gemeinsames COMMAND_REGISTRY in hermes_cli/commands.py verteilt, weshalb die meisten Befehle auf allen Oberflächen identisch funktionieren.⁹

Sitzungssteuerung

Konfiguration & Modell

Der Befehl /model ist das Arbeitstier für den Provider-Wechsel mitten in der 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 & Infos

Dynamische Skill-Slash-Befehle

Jeder installierte Skill wird automatisch als Slash-Befehl bereitgestellt:⁹

/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 in config.yaml zudem Quick Commands 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"

Tippen Sie dann /review, /deploy oder /morning in der CLI.

Präfix-Matching

Befehle unterstützen Präfix-Matching: Die Eingabe /h wird zu /help aufgelöst, /mod zu /model. Bei einem mehrdeutigen Präfix gewinnt die erste Registrierung in der Registry-Reihenfolge. Vollständige Befehlsnamen und registrierte Aliase haben immer Vorrang vor Präfix-Treffern.⁹

Messaging-spezifische Befehle

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

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

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

Tools & Toolsets

Hermes wird mit einer umfangreichen integrierten Tool-Registry ausgeliefert, die Websuche, Browser-Automatisierung, Terminal-Ausführung, Datei-Bearbeitung, Memory, Delegation, RL-Training, Messaging-Zustellung, Home Assistant-Integration und vieles mehr abdeckt.¹⁰ Tools sind in logische Toolsets organisiert, die pro Plattform aktiviert oder deaktiviert werden können.

Übergeordnete Kategorien

Gängige Toolset-Namen umfassen 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 auch mitten in einer Session über /tools disable <name> und /tools enable <name> umgeschaltet werden, was die Session zurücksetzt, damit das neue Tool-Set 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 (empfohlen aus Sicherheitsgründen — der Agent kann seinen eigenen Code nicht modifizieren):¹⁰

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 überdauern installierte Pakete, Dateien und Konfigurationen mehrere Sessions.¹⁰

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

Hintergrundprozesse

Das Terminal-Tool unterstützt Hintergrundausführung mit expliziter Prozessverwaltung:¹⁰

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 Session zwischengespeichert). Alternativ können Sie SUDO_PASSWORD in ~/.hermes/.env setzen.¹⁰

Multi-Agent Kanban (v0.13.0+)

v0.13.0 macht Multi-Agent-Kollaboration zu einem erstklassigen Primitiv: ein dauerhaftes Kanban-Board, das Aufgaben, Status und Worker-Identität über Agenten und Neustarts hinweg verfolgt.¹⁸ Das Board ist das, was einem Schwarm aus Hermes-Workern ermöglicht, Arbeit tatsächlich abzuschließen, statt an toten Übergaben zu stocken.

Das Kanban-Board passt natürlich zu /goal (Ralph-Loop mit fixiertem Ziel) auf der Zielseite und zum bestehenden delegate_task-Tool für die Spawn-Semantik. Das Ergebnis ist ein Schwarmmuster, bei dem jeder Agent eine einzige Quelle der Wahrheit darüber teilt, was als Nächstes zu tun ist, wer es tut und was feststeckt.

Skills-System

Skills sind bei Bedarf ladbare Wissensdokumente, die der Agent laden kann, wenn er sie benötigt. Sie folgen einem Muster der progressiven Offenlegung, um den Token-Verbrauch zu minimieren, und sind kompatibel mit dem offenen Standard von agentskills.io.¹¹

Alle Skills liegen in ~/.hermes/skills/ — dem primären Verzeichnis und der Quelle der Wahrheit. Bei einer Neuinstallation werden mitgelieferte Skills aus dem Repo kopiert. Über den Hub installierte und vom Agenten 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.¹¹

SKILL.md-Format

---
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

## Verifizierung
So bestätigen Sie, dass es funktioniert hat.

Bedingte Aktivierung

Skills können sich selbst ein- oder ausblenden, basierend darauf, welche Tools verfügbar sind. Dies ist besonders nützlich für Fallback-Skills — kostenlose oder lokale Alternativen, die nur erscheinen sollen, wenn ein Premium-Tool nicht verfügbar ist:¹¹

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

Vom Agenten verwaltete Skills

Der Agent kann seine eigenen Skills über das skill_manage-Tool erstellen, aktualisieren und löschen. Dies ist das prozedurale Gedächtnis des Agenten — wenn er einen nicht trivialen Workflow ausarbeitet, 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 Pfad gefunden hat - Wenn der Benutzer seinen Ansatz korrigiert hat - Wenn er einen nicht trivialen Workflow entdeckt hat

Aktionen:¹¹

Skill Hub

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

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 aus dem Hub installierten Skills durchlaufen einen Sicherheits-Scanner, der auf Datenabfluss, 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-Scan-Urteil.¹¹

Externe Skill-Verzeichnisse

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

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

Pfade unterstützen ~-Erweiterung und ${VAR}-Substitution von Umgebungsvariablen. Externe Verzeichnisse sind schreibgeschützt — wenn der Agent einen Skill erstellt oder bearbeitet, schreibt er immer in ~/.hermes/skills/. Die lokale Priorität gewinnt, falls ein Skill-Name an beiden Orten existiert.¹¹

Persistentes Gedächtnis

Hermes verfügt über ein begrenztes, kuratiertes Gedächtnis, das über Sessions hinweg bestehen bleibt. Zwei Dateien bilden das Gedächtnis des Agenten, beide gespeichert in ~/.hermes/memories/:¹²

Beide werden als eingefrorener Snapshot beim Session-Start in den System-Prompt injiziert. Der Agent verwaltet sein eigenes Gedächtnis über das memory-Tool — add, replace oder remove.¹²

Eingefrorenes Snapshot-Muster: Die Injektion in den System-Prompt wird einmal beim Session-Start erfasst und ändert sich während der Session nicht mehr. Dies ist beabsichtigt — es bewahrt den Prefix-Cache des LLM für Performance. Während einer Session vorgenommene Änderungen werden sofort auf Festplatte persistiert, erscheinen aber erst beim nächsten Session-Start im System-Prompt.¹²

Was zu speichern ist

Speichern Sie diese (der Agent tut dies proaktiv):¹² - Benutzerpräferenzen: „Ich bevorzuge TypeScript gegenüber JavaScript” → user - Umgebungsfakten: „Dieser Server läuft mit Debian 12 und PostgreSQL 16” → memory - Korrekturen: „Verwende kein sudo für Docker-Befehle, der Benutzer ist in der docker-Gruppe” → memory - Konventionen: „Projekt verwendet Tabs, 120-Zeichen-Zeilenbreite, Google-style Docstrings” → memory - Abgeschlossene Arbeit: „Datenbank am 15.01.2026 von MySQL zu PostgreSQL migriert” → memory

Diese überspringen:¹² - Triviale/offensichtliche Informationen - Leicht wieder auffindbare Fakten - Rohdaten-Dumps (zu groß für das Gedächtnis) - Session-spezifische Ephemera - Informationen, die bereits in Kontextdateien enthalten sind

Session-Suche

Über MEMORY.md und USER.md hinaus kann der Agent seine vergangenen Konversationen mit dem session_search-Tool durchsuchen. Alle CLI- und Messaging-Sessions werden in SQLite (~/.hermes/state.db) mit FTS5-Volltextsuche gespeichert. Anfragen liefern relevante vergangene Konversationen mit Gemini-Flash-Zusammenfassung zurück.¹²

Externe Memory Provider

Für tieferes persistentes Gedächtnis über MEMORY.md und USER.md hinaus liefert Hermes acht externe Memory-Provider-Plugins mit: Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover und Supermemory.¹²

Externe Provider laufen neben dem eingebauten Gedächtnis (ersetzen es nie) und fügen Funktionen wie Knowledge Graphs, semantische Suche, automatische Faktenextraktion und sessionübergreifende Benutzermodellierung hinzu:⁶¹²

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)

Nur ein externer Provider kann gleichzeitig aktiv sein. Das eingebaute Gedächtnis ist immer aktiv.⁶

Session Auto-Resume (v0.13.0+)

v0.13.0 macht Unterbrechungen mitten im Agentenlauf überlebbar. Das gateway nimmt unterbrochene Sessions nach einem Neustart automatisch wieder auf; /update-Neustarts erhalten den Session-Status durch das Upgrade hindurch; Reloads von Quelldateien während der Entwicklung halten die aktive Session am Leben, anstatt eine neue zu erzwingen.¹⁸ Praktischer Effekt: Lang laufende gateway-Arbeiten und cron-gesteuerte Jobs setzen ihr Kontextfenster nicht mehr zurück, wenn der Prozess neu startet.

Checkpoints v2 (v0.13.0+)

Die Zustandspersistenz ist in v0.13.0 als Single-Store-Design neu geschrieben — mit echtem Pruning, Disk-Schutzmaßnahmen und ohne verwaiste Shadow-Repos.¹⁸ Das frühere checkpoint-System sammelte über lang laufende profile hinweg Zustand auf der Festplatte an; der v2-Store setzt eine harte Obergrenze für lokalen checkpoint-Speicher und entfernt die duplizierte Buchhaltung, die dieses Wachstum antrieb. Es ist keine benutzerseitige Konfigurationsänderung erforderlich; der nächste checkpoint-Write verwendet 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 eincodierte Standardidentität.¹³

Hermes legt automatisch eine Standard-SOUL.md unter ~/.hermes/SOUL.md (oder $HERMES_HOME/SOUL.md bei benutzerdefinierten Profilen) an. Bestehende Benutzerdateien werden nie überschrieben. Hermes lädt SOUL.md ausschließlich aus HERMES_HOME — im aktuellen Arbeitsverzeichnis wird nicht gesucht. Dadurch bleibt die Persönlichkeit projektübergreifend vorhersehbar.¹³

Was in SOUL.md gehört

Verwenden Sie sie für dauerhafte Vorgaben zu Stimme und Persönlichkeit:¹³ - Tonfall - Kommunikationsstil - Direktheitsgrad - Standard-Interaktionsstil - Was stilistisch zu vermeiden ist - Wie Hermes mit Unsicherheit, Meinungsverschiedenheiten und Mehrdeutigkeit umgehen soll

Weniger geeignet ist sie 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

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

SOUL.md — Identität, Tonfall, Stil, Kommunikationsvorgaben, Verhalten auf Persönlichkeitsebene.

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

Eine nützliche Faustregel: 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.¹³

Eingebaute Persönlichkeiten

Hermes liefert eingebaute 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 Grundstimme. /personality ist eine Überlagerung auf Sitzungsebene.¹³ Pflegen Sie eine pragmatische Standard-SOUL.md und nutzen Sie dann /personality teacher für ein Lerngespräch oder /personality creative zum Brainstorming.

Nous Tool Gateway (v0.10.0+)

Seit Hermes Agent v0.10.0 (16.04.2026) erhalten zahlende Nous Portal-Abonnenten verwalteten Zugang zu einer kuratierten Auswahl von Tools über ihre bestehenden Portal-Anmeldedaten — keine zusätzlichen API-Schlüssel zu verwalten.²⁰ Die Hermes CLI selbst bleibt MIT-lizenziert und vollständig Open Source. Geändert hat sich, dass Ihre Portal-Authentifizierung nun mehr als nur Modell-Inferenz freischaltet.

Was im Gateway enthalten ist

Funktionsweise

Das Gateway ist pro Tool optional aktivierbar über ein neues Konfigurationsfeld use_gateway. Wenn Sie Portal-Anmeldedaten in hermes auth haben und das Gateway für ein Tool aktivieren, werden die Aufrufe dieses Tools über das Portal geleitet. Andernfalls wird Ihr direkter API-Schlüssel (sofern 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

Laufzeit-Vorrang: Wenn das Gateway verfügbar ist und ein Tool use_gateway: true gesetzt hat, bevorzugt Hermes das Gateway, selbst wenn Sie zusätzlich einen direkten API-Schlüssel konfiguriert haben. Das ist für die Abrechnung relevant — Gateway-Aufrufe werden Ihrem Portal-Abonnement belastet, nicht dem Guthaben Ihres direkten API-Schlüssels.

Aktivierung des Gateways

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 aus den Portal-OAuth-Anmeldedaten erkannt, die Sie bereits in hermes auth hinterlegt haben.

Preise und Zugang

Preise und Tarifnamen werden auf der Preisseite des Nous Portal veröffentlicht (https://portal.nousresearch.com/pricing). In dieser Anleitung werden die Tarife nicht aufgeführt, da sie in der Verantwortung des Portal-Produkts liegen, 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 für die aktuellen Tarife.

Deprecation-Hinweis

• Die Umgebungsvariable HERMES_ENABLE_NOUS_MANAGED_TOOLS wurde in v0.10.0 entfernt. Verwaltete Tools werden nun über das Konfigurationsfeld use_gateway pro Tool aktiviert und sind an den Status Ihres Portal-Abonnements gekoppelt.²⁰

Einordnung: Was dieses Release nicht ist

Die Hermes Agent CLI ist nicht hinter einem Abonnement gesperrt. Das Projekt ist weiterhin MIT-lizenziert, alle Kernfunktionen (CLI, Skills, Memory, Messaging-Gateway, Cron, MCP, lokales Dashboard, BYOK für jeden Anbieter) funktionieren durchgängig, ohne dass Sie irgendjemanden bezahlen müssen. v0.10.0 fügt einen Komfortpfad für Benutzer hinzu, die ohnehin schon für Nous Portal zahlen — am freien Pfad wird nichts weggenommen.

Messaging Gateway

Hermes kann als langlaufender Gateway-Prozess laufen, der aus einem einzigen Prozess heraus Verbindungen zu 20 Messaging-Plattformen herstellt: Telegram, Discord, Slack, WhatsApp, Signal, SMS, E-Mail, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat sowie einen generischen Webhook-Adapter.^3191718 v0.9.0 ergänzte iMessage via BlueBubbles (automatische Webhook-Registrierung, Setup-Assistent, Crash-Resilienz) und native WeChat-Unterstützung über die iLink Bot API mit WeCom-Callback-Modus für Unternehmens-Apps.¹⁶ v0.11.0 fügte QQBot hinzu.¹⁹ v0.12.0 ergänzte Microsoft Teams und Tencent Yuanbao.¹⁷ v0.13.0 nahm Google Chat als 20. Plattform auf — auf derselben pluggable Adapter-Architektur; IRC und Microsoft Teams wurden ebenfalls auf das neue Adapter-Pattern mit generischen Plugin-Hooks env_enablement_fn / cron_deliver_env_var migriert.¹⁸

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 Anbindung jeder Plattform: API-Tokens, Bot-IDs, Channel-Zuordnungen, Allowlists.⁶

Wie Nachrichten fließen

Aus der vorgelagerten Architekturdokumentation:³

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 durchläuft dieselbe AIAgent-Konversationsschleife wie die CLI. Deshalb funktionieren Slash-Befehle an beiden Stellen identisch, und deshalb kann ein in Telegram geplanter Cron-Job seine Ausgabe an Discord ausliefern — der Plattformunterschied liegt nur am Rand.³

Benutzerautorisierung & 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 kommunizieren. Ein Benutzer sendet einen Pairing-Code von seiner Messaging-Plattform; Sie genehmigen ihn mit hermes pairing approve; ab diesem Zeitpunkt ist er autorisiert.⁶

Geplante Aufgaben (Cron)

Hermes verfügt über ein erstklassiges Cron-System, in dem Jobs Agent-Aufgaben sind, keine Shell-Befehle. Jeder geplante Job läuft durch einen frischen AIAgent mit dem konfigurierten Prompt, optional angehängten Skills, und liefert die Ergebnisse an eine beliebige 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 konversationell direkt in einem Messaging-Chat:

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 werden in JSON persistiert 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 Agenten zur Verfügung:

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 einen beliebigen Provider oder Endpunkt 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 den vollständigen Mittelteil der Konversation zur Komprimierung erhält.⁴

Budget-Druck-Warnungen

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

Stream-Timeouts

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

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

Lokales Web-Dashboard (v0.9.0+)

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

Hintergrundprozess-Überwachung (v0.9.0+)

watch_patterns ermöglicht es Ihnen, Muster zur Überwachung in der Ausgabe von Hintergrundprozessen festzulegen und in Echtzeit benachrichtigt zu werden, wenn diese übereinstimmen.¹⁶ Überwachen Sie auf Fehler, warten Sie auf bestimmte Ereignisse („listening on port”) oder beobachten Sie Build-Logs — alles ohne Polling. Kombiniert mit notify_on_complete aus v0.8.0 (das bei Abschluss von Hintergrundaufgaben benachrichtigt) verfügt Hermes nun über eine vollständige Beobachtungsschicht für Hintergrundprozesse.¹⁵

Pluggable Context Engine (v0.9.0+)

Das Kontextmanagement ist nun ein steckbarer Slot über hermes plugins. Tauschen Sie benutzerdefinierte context engines ein, die steuern, was der Agent in jedem Durchlauf sieht — Filterung, Zusammenfassung oder domänenspezifische Kontexteinspeisung.¹⁶ Dies entkoppelt die Kontextstrategie von der Kern-Agent-Schleife und ermöglicht eine projekt- oder domänenspezifische Kontextanpassung.

Backup & Wiederherstellung (v0.9.0+)

hermes backup erstellt ein vollständiges Archiv Ihrer Konfiguration, Sessions, Skills und Speicher. hermes import stellt aus einem Backup-Archiv wieder her.¹⁶ Verwenden Sie dies, um zwischen Maschinen zu migrieren, vor größeren Änderungen Snapshots zu erstellen oder eine bekannt funktionierende Konfiguration mit Teamkollegen 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, Voice-Backend-Unterstützung und der /image-Befehl funktionieren on-device.¹⁶

Security Hardening (v0.13.0+)

v0.13.0 hat 8 P0-Sicherheitsprobleme geschlossen und einen Standard zugunsten des Benutzers geändert.¹⁸

Wenn Sie eine Hermes-Bereitstellung pflegen, behandeln Sie v0.13.0 als sicherheitsrelevantes Upgrade, nicht nur als Feature-Drop. Der Discord-Cross-Guild-Bypass und die beiden TOCTOU-Fenster sind auf früheren Versionen ausnutzbar.

Architektur für Praktiker

Dieser Abschnitt richtet sich an Personen, die verstehen möchten, was unter der Haube passiert, um es zu debuggen, zu erweitern oder über die Performance zu urteilen. Es handelt sich um eine Synthese der vorgelagerten 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 angepasst aus der vorgelagerten Architekturdokumentation.³

„47 tools / 20 toolsets” vs. „28 tools” in Ihrem Banner. Die Zahl „47 tools” ist die Gesamtzahl der Tool-Registry des vorgelagerten Repositorys — jedes Tool, für das Hermes Quellcode mitliefert, über alle toolsets hinweg. Ihr tatsächlich laufender CLI zeigt im Startbanner eine kleinere Zahl an (die Installation, gegen die ich diese Anleitung verifiziert habe, meldet 28 tools / 89 skills). Das ist kein Fehler. Viele toolsets sind opt-in und müssen explizit in config.yaml unter toolsets: aktiviert werden — Adapter für Messaging-Plattformen, Browser-Automatisierung, schwerere Scraping-Tools und so weiter. Die Gesamtzahl der Registry beschreibt „was verfügbar ist”; die Bannerzahl beschreibt „was im aktuellen profile aktiviert ist.” Prüfen Sie mit hermes tools --list, welche toolsets aktiv sind, und aktivieren oder deaktivieren Sie einzelne toolsets über den toolsets:-Block in ~/.hermes/config.yaml (oder /tools list / /tools enable <name> / /tools disable <name> innerhalb einer laufenden Session — das Entfernen eines Tools löst einen Session-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 Resolver runtime_provider.py ordnet (provider, model)-Tupel auf (api_mode, api_key, base_url) für mehr als 18 Provider ab und kümmert sich um OAuth-Flows, Credential-Pools und Alias-Auflösung.³

Datenfluss durch eine CLI-Session

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

Aus der vorgelagerten Architekturseite.³

Reihenfolge des Prompt-Aufbaus

Der Prompt-Stack umfasst:¹³

1. SOUL.md (Agent-Identität — oder integrierter Fallback, falls nicht verfügbar)
2. Tool-bewusste Verhaltensanleitung
3. Memory/Benutzerkontext (MEMORY.md, USER.md)
4. Skills-Anleitung
5. Kontext-Dateien (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.¹³

Session-Speicher

SQLite-basierter Session-Speicher mit FTS5-Volltextsuche. Sessions verfügen über Lineage-Tracking (Parent/Child über Komprimierungen hinweg), pro-Plattform-Isolation sowie atomare Schreibvorgänge mit Konfliktbehandlung.³

Plugin-System

Drei Discovery-Quellen: ~/.hermes/plugins/ (Benutzer), .hermes/plugins/ (Projekt) und pip-Entry-Points. Plugins registrieren Tools, Hooks und CLI-Befehle über eine 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

Aus der vorgelagerten 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 zudem automatisch die Legacy-Verzeichnisse ~/.clawdbot und ~/.moldbot) und schreibt nach ~/.hermes.⁶

Direkt importiert (mehr als 30 Kategorien): SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills aus 4 Quellverzeichnissen, Standardmodell, Custom Provider, MCP-Server, Tokens und Allowlists für Messaging-Plattformen (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), Agent-Defaults (Reasoning-Aufwand, Komprimierung, Human-Delay, Zeitzone, Sandbox), Session-Reset-Richtlinien, Approval-Regeln, TTS-Konfiguration, Browser-Einstellungen, Tool-Einstellungen, Exec-Timeout, Befehls-Allowlist, gateway-Konfiguration sowie API-Schlüssel aus 3 Quellen.⁶

Archiviert zur manuellen Überprüfung: cron-Jobs, Plugins, Hooks/Webhooks, Memory-Backend (QMD), Skills-Registry-Konfiguration, UI/Identität, Logging, Multi-Agent-Setup, Channel-Bindings, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

Die Auflösung der API-Schlüssel prüft drei Quellen in priorisierter Reihenfolge: 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