Last updated on

Ich habe jede Zeile der Hermes config.yaml optimiert — 3 Einstellungen, die lange Aufgaben nicht hängen lassen

Das Frustrierendste an der Verwendung von Hermes Agent für komplexe Aufgaben ist nicht eine falsche Antwort — sondern zuzusehen, wie der Job auf halbem Weg einfriert: API-Aufrufe hängen, die Kontextlänge explodiert nach vielen Turns, oder ein fehlgeschlagenes Tool steckt in einer endlose Wiederholungsschleife fest. Meistens sind das keine Modellprobleme. Es sind Standardwerte in ~/.hermes/config.yaml, die nicht für lange laufende Aufgaben abgestimmt sind.

Nachdem ich Hunderte lange Aufgaben ausgeführt habe, habe ich meine Config Zeile für Zeile durchgegangen und festgestellt, dass nur drei Einstellungen wirklich darüber entscheiden, ob eine lange Aufgabe reibungslos zu Ende kommt. Passen Sie sie an Ihre Workload an, und die meisten komplexen Jobs laufen ohne manuelles Eingreifen bis zur Fertigstellung durch.

Im Folgenden folgt jeder Abschnitt dem Muster: Symptom → Ursache → Lösung → empfohlene Werte, mit Copy-Paste-YAML-Snippets.

Einstellung 1: API-Aufrufe streng an die Leine nehmen — Provider-Timeouts

Symptome

  • Die Aufgabe erreicht 50 %, das Terminal verstummt, und nach dreißig Sekunden erscheint „Connection timed out.“
  • Ein Hintergrund- oder Cron-Job zeigt running an, aber das Log bewegt sich seit Minuten nicht.
  • Nach dem Wechsel zu einem anderen OpenRouter-Provider werden die Antworten unberechenbar und hängen gelegentlich komplett.

Ursache

Hermes-API-Aufrufe greifen standardmäßig auf zwei Umgebungsvariablen zurück: HERMES_API_TIMEOUT (1800 s) und HERMES_API_CALL_STALE_TIMEOUT (90 s). Allerdings haben die Schlüssel request_timeout_seconds und stale_timeout_seconds unter dem providers-Block in config.yaml Vorrang; die Umgebungsvariablen werden nur verwendet, wenn keine Config gesetzt ist.

Ohne per-Provider-Abstimmung:

  • Cloud-Modelle mit langem Denken (Claude Opus, o1, deep-research) können vor Fertigstellung abgebrochen werden.
  • Lokale Endpunkte (LM Studio, Ollama, vLLM) können beim Cold-Start Zehn Sekunden brauchen, aber die Standard-Request-Timeouts sind viel kürzer.
  • Ein einzelner wackeliger Provider kann den gesamten Lauf blockieren, weil es kein explizites Timeout gibt.

Lösung

Fügen Sie einen providers-Block am Anfang der config.yaml hinzu und passen Sie ihn pro Provider an:

providers:
  anthropic:
    request_timeout_seconds: 600      # tolerate 10 min for slow thinking
    stale_timeout_seconds: 300      # non-streaming calls only
  openrouter:
    request_timeout_seconds: 300
    stale_timeout_seconds: 120
  lmstudio:
    request_timeout_seconds: 300      # local cold-start is slow
    stale_timeout_seconds: 900        # explicitly re-enable stale detection
  ollama-local:
    request_timeout_seconds: 300
    stale_timeout_seconds: 900

Wenn Sie hauptsächlich einen Provider nutzen, reicht es, genau diesen zu konfigurieren. request_timeout_seconds wird direkt als timeout= an das SDK übergeben und überschreibt die ältere Umgebungsvariable.

Empfohlene Werte

Szenario request_timeout_seconds stale_timeout_seconds
Schnelle Cloud-Modelle (Claude 3.5 Sonnet, GPT-4o mini) 60–120 60–90
Modelle mit langem Denken (Claude Opus, o1, deep-research) 300–600 120–300
Lokale Modelle (LM Studio / Ollama / vLLM) 180–300 600–900
Hintergrund- / Cron-Jobs 300–600 120–300

Hinweis: stale_timeout_seconds gilt nur für Nicht-Streaming-Aufrufe. Streaming-Aufrufe gelten so lange als aktiv, wie weiterhin Tokens ankommen.

Einstellung 2: Nicht zuerst den Kontext explodieren lassen — Komprimierungsstrategie

Symptome

  • Nach vielen Tool-Turns fängt das Modell an, neben dem Thema zu antworten, oder wirft „context length exceeded“.
  • Die Komprimierung greift zu spät, bei 80 % des Fensters, und komprimiert bereits wichtige Zwischenergebnisse weg.
  • Nach der Komprimierung „vergisst“ der Agent Dinge, die Sie gerade bestätigt haben: API-Schlüssel, Dateipfade, Einschränkungen.

Ursache

Der compression-Block von Hermes wird ausgelöst, wenn die Token-Nutzung threshold × context_length erreicht. Die Standardwerte passen möglicherweise nicht zu Ihrer Workload:

  • threshold: 0.50 ist aggressiv für einen 200K-Kontext, aber zu spät für einen 32K-Kontext.
  • protect_last_n: 20 behält nur die letzten 20 Nachrichten, was bei einer langen Aufgabe nur 2–3 kritische Turns abdecken kann.
  • target_ratio: 0.20 entscheidet, wie viel vom aktuellen Ende behalten wird; zu klein verliert Details, zu groß verschwendet Platz.

Es gibt auch eine versteckte Regel im Code: Bei Modellen mit einem Kontextfenster unter 512K wird der Threshold auf 0,75 begrenzt. Kleinfenster-Modelle lösen also gar nicht bei 50 % aus, sondern bei 75 %. Das hilft dabei, den echten Komprimierungspunkt abzuschätzen.

Lösung

compression:
  enabled: true
  threshold: 0.65           # trigger earlier than default
  target_ratio: 0.25        # keep 25% recent tail
  protect_last_n: 30        # ~15 full turns
  protect_first_n: 1        # only system prompt + first user message
  codex_app_server_auto: native

Wenn Ihre Aufgabe häufig frühen Kontext benötigt (z. B. „immer Python 3.11 verwenden“, „dieses Projekt nutzt pnpm“), erhöhen Sie protect_first_n auf 3. Ansonsten lassen Sie es bei 1, um Platz zu sparen.

Empfohlene Werte

Modell-Kontext threshold target_ratio protect_last_n
≤ 32K (Claude 3.5 Sonnet, GPT-4o) 0.75 (default floor) 0.25 30–40
128K–200K 0.60–0.65 0.20–0.25 20–30
≥ 1M (Gemini, Kimi k1.5) 0.50–0.55 0.15–0.20 20

Tipp: Der Komprimierungs-Summarizer verwendet standardmäßig Gemini Flash, das schnell und günstig ist. Für code-lastige Aufgaben können Sie unter auxiliary.compression ein anderes Modell festlegen, aber der Standard reicht meist.

Einstellung 3: Die Tool-Schleife festlegen — agent.max_turns

Symptome

  • Eine einfache Aufgabe ruft 50 Tool-Turns auf und der Agent sagt immer noch „let me double-check“.
  • Ein kurzer Netzwerk-Aussetzer lässt ein Tool wiederholt fehlschlagen, sodass der Agent in eine Retry-Spirale gerät und Ihre Rechnung steigt.
  • Ein Hintergrund-Task läuft eine halbe Stunde und steckt sich dann als Schleife fest.

Ursache

agent.max_turns begrenzt, wie viele Tool-Calling-Iterationen der Agent in einer einzigen Benutzeranfrage ausführen kann. Der Standardwert 60 reicht für lässiges Q&A, aber er wird bei komplexem Debugging, Batch-Verarbeitung oder iterativer Bestätigung schnell aufgebraucht. Ohne Obergrenze kann ein fehlgeschlagenes Tool unendlich oft wiederholen.

Die Kombination von max_turns mit tool_loop_guardrails.hard_stop_enabled schafft einen Circuit Breaker für anomale Schleifen.

Lösung

agent:
  max_turns: 100              # room for complex tasks
  api_max_retries: 2          # fail fast and let fallback take over
  reasoning_effort: medium

tool_loop_guardrails:
  warnings_enabled: true
  hard_stop_enabled: true     # circuit breaker for abnormal loops
  warn_after:
    exact_failure: 2
    same_tool_failure: 3
    idempotent_no_progress: 2
  hard_stop_after:
    exact_failure: 5
    same_tool_failure: 8
    idempotent_no_progress: 5

Empfohlene Werte

Aufgabentyp max_turns hard_stop_enabled
Lässiges Q&A / Einzelschritt-Abfragen 30–40 false
Code-Debugging / mittlere Komplexität 60–80 true
Batch-Verarbeitung / lange Hintergrund-Jobs 100–150 true
Explorative Forschung / Multi-File-Refactoring 100–200 true

Hinweis: max_turns ist das Limit für Tool-Iterationen pro Anfrage, nicht die lebenslange Nachrichtenbegrenzung der gesamten Sitzung. Sie können den Kontext jederzeit mit /new oder anderen Session-Management-Befehlen aus unserem Hermes v0.18 Befehls-Überblick zurücksetzen.

Komplette Referenz: Ein sofort einsatzbereites config.yaml-Snippet

Hier ist ein zusammengefasstes Snippet für die gängige Einrichtung: OpenRouter als primärer Provider, gelegentlich lokale Modelle und häufig lange Aufgaben:

model:
  default: "anthropic/claude-opus-4.6"
  provider: "auto"
  base_url: "https://openrouter.ai/api/v1"

providers:
  anthropic:
    request_timeout_seconds: 600
    stale_timeout_seconds: 300
  openrouter:
    request_timeout_seconds: 300
    stale_timeout_seconds: 120
  lmstudio:
    request_timeout_seconds: 300
    stale_timeout_seconds: 900

compression:
  enabled: true
  threshold: 0.65
  target_ratio: 0.25
  protect_last_n: 30
  protect_first_n: 1
  codex_app_server_auto: native
  codex_gpt55_autoraise: true

agent:
  max_turns: 100
  api_max_retries: 2
  reasoning_effort: medium

tool_loop_guardrails:
  warnings_enabled: true
  hard_stop_enabled: true
  warn_after:
    exact_failure: 2
    same_tool_failure: 3
    idempotent_no_progress: 2
  hard_stop_after:
    exact_failure: 5
    same_tool_failure: 8
    idempotent_no_progress: 5

Speichern Sie es unter ~/.hermes/config.yaml. Neue Sitzungen übernehmen sie sofort; bereits laufende Sitzungen benötigen /new, um sie neu zu laden.

Überprüfung: Hat es tatsächlich geholfen?

Drei schnelle Checks:

  1. Langes Denken gezielt auslösen. Bitten Sie den Agent, eine 500-zeilige Log-Datei zu verarbeiten oder zehn Quelldateien auf einmal zu lesen. context length exceeded sollte nicht mehr auftreten.
  2. API-Jitter simulieren. Blockieren Sie kurzzeitig die Provider-IP mit timeout oder iptables und bestätigen Sie, dass der Agent innerhalb des konfigurierten Timeouts fehlschlägt und Fallback versucht, anstatt ewig zu hängen.
  3. Komprimierung prüfen. Führen Sie während einer langen Aufgabe /compress aus oder warten Sie auf die automatische Komprimierung, und überprüfen Sie, ob die letzten ~30 Nachrichten und der System-Prompt noch vorhanden sind.

Für komplexere Fehlerfälle lesen Sie unseren Deep Dive zu Hermes error handling and recovery, der Timeouts, Fallbacks und Retries zu einer einzigen Resilienz-Strategie verbindet.

Zusammenfassung

Lange Aufgaben bleiben meist nicht hängen, weil das Modell dümmer geworden wäre, sondern weil API-Timeouts, Kontextkomprimierung und Tool-Loop-Limits nicht aufeinander abgestimmt sind. Nach der Abstimmung dieser drei Einstellungen:

  • API-Aufrufe laufen sauber aus und greifen auf einen anderen Provider zurück, anstatt zu hängen.
  • Der Kontext komprimiert sich im richtigen Moment, bewahrt aktuelle Details und erreicht nicht das Fensterlimit.
  • Tool-Aufrufe haben eine harte Obergrenze, die Retry-Spiralen und explodierende Kosten verhindert.

Wenn Sie gerade erst anfangen, lesen Sie zuerst die Installationsanleitung, um sicherzustellen, dass Ihre Umgebung stabil ist, und behalten Sie dieses Snippet als „Long-Task-Template“ zum Kopieren für anspruchsvolle Aufgaben.

Quellen: Dieser Artikel basiert auf dem offiziellen Hermes Agent cli-config.yaml.example und der offiziellen Dokumentation.