Hermes Agent

Ein benannter Anbieter in ~/.hermes/config.yaml — api https://api.kunavo.com, transport anthropic_messages, ausgewählt mit provider: custom:kunavo — verbindet Hermes Agent über das Messages-Protokoll mit Claude. Dabei sendet Hermes Agent eigene Cache-Markierungen und ein Ausgabelimit.

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com        # origin — the Anthropic SDK adds /v1/messages
    key_env: KUNAVO_API_KEY            # the variable's NAME; the key goes in ~/.hermes/.env
    transport: anthropic_messages
    models:
      claude-sonnet-5:
        context_length: 1000000
        prompt_caching: true
      claude-haiku-4-5:
        context_length: 200000
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

Schritt für Schritt

1. Erstellen Sie unter /app/keys einen Schlüssel und kopieren Sie ihn — er wird nur einmal angezeigt.
2. Speichern Sie den Schlüssel dort, wo Hermes vertrauliche Daten ablegt: hermes config set KUNAVO_API_KEY sk-kn-... schreibt ihn nach ~/.hermes/.env. Die Zeile key_env im Block gibt den Namen dieser Variable an; der Schlüssel selbst gehört nicht in config.yaml.
3. Fügen Sie den Block zu ~/.hermes/config.yaml hinzu — mit hermes config edit öffnen Sie die Datei. Wenn bereits ein Abschnitt model: vorhanden ist, ersetzen Sie dessen default und provider und lassen Sie den Rest unverändert.
4. Oder lassen Sie den Einrichtungsassistenten die Konfiguration schreiben: Führen Sie hermes model in einem Terminal aus, außerhalb einer Chatsitzung, wählen Sie Custom endpoint (self-hosted / VLLM / etc.) und beantworten Sie die Eingabeaufforderungen — zur API-Basis-URL, zum Schlüssel, Modellnamen, API-Modus und zur Kontextlänge.
5. Starten Sie hermes und lesen Sie das Banner: Dort werden das Modell und sein Kontextfenster angezeigt, und beide sollten mit dem Block übereinstimmen.
6. Senden Sie zwei Nachrichten und öffnen Sie /usage, um zu sehen, welche Ressourcen die Durchläufe verbraucht haben. Um das Modell innerhalb einer Sitzung zu ändern, verwenden Sie /model custom:kunavo:claude-opus-5-5.

Abgeglichen mit Die Seite zu KI-Anbietern von Hermes Agent am 5. Oktober 2026. Einstellungen von Drittanbietern können sich ändern; wenn ein Feldname hier nicht mehr mit deiner Ansicht übereinstimmt, ist diese Seite maßgeblich, nicht diese hier.

Vor dem Debugging des Clients prüfen

Eine Anfrage klärt, ob der Fehler am Endpunkt, am Schlüssel oder an der Konfigurationsdatei liegt. Wenn diese Anfrage JSON zurückgibt, funktionieren dieselbe Basis-URL und derselbe Schlüssel in Hermes Agent.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Welche Modell-ID in das Feld gehört

Jedes Textmodell ist über eine Modell-ID erreichbar – die aktuelle Liste findest du unter GET /v1/models, den Katalog mit Preisen auf der Modellseite. Die Tarife sind USD pro 1 Mio. Token, Eingabe / Ausgabe.

Das OpenAI-kompatible Protokoll

Derselbe Schlüssel erreicht jede andere Modellfamilie über /v1/chat/completions. Dafür genügt die kürzeste in der Hermes-Dokumentation beschriebene Form – ein model:-Block mit provider: custom und base_url, wie auch von hermes model verlangt:

# ~/.hermes/config.yaml — the bare form, for an OpenAI-compatible endpoint
model:
  default: gpt-6-sol
  provider: custom
  base_url: https://api.kunavo.com/v1    # this wire keeps /v1
  key_env: KUNAVO_API_KEY
  context_length: 1050000

Die Basis-URL enthält hier weiterhin /v1, entsprechend der Form, die Hermes in der Dokumentation für Beispiele mit lokalen Servern verwendet. Mit context_length wird das Kontextfenster festgelegt, sodass Hermes es nicht erkennen muss. Damit beide Transportarten gleichzeitig konfiguriert sind, legen Sie für diese Transportart — transport: chat_completions — einen eigenen benannten Eintrag an und wechseln Sie mit /model custom:<name>:<model>.

Prompt-Caching auf den verschiedenen Protokollen

Beim Anthropic-Transport fügt Hermes die Cache-Markierungen selbst hinzu. Für einen benutzerdefinierten Anbieter dokumentiert die Seite Modelle konfigurieren die Einstellung für den oben gezeigten Block – prompt_caching: true beim Modell – und erläutert, dass das Layout vom Transport abhängt: native Blöcke bei anthropic_messages, das Envelope-Layout beim OpenAI-kompatiblen Transport. Kunavos /v1/messages leitet den Request-Body unverändert weiter und fügt keine eigenen Breakpoints hinzu. Bei diesem Transport stammen die Markierungen daher von Hermes oder es gibt keine.

Bei benutzerdefinierten Endpunkten lässt die Hermes-Dokumentation die Gültigkeitsdauer offen. prompt_caching.cache_ttl – 5m, 1h oder auto – wird für Claude über die native Anthropic-API, OpenRouter und Nous Portal beschrieben; zu anderen Endpunkten gibt es keine Angaben. Kunavo leitet die jeweils empfangene Markierung weiter und berechnet Schreibzugriffe zum gleichen Preis. Prüfen Sie daher Ihre eigenen Nutzungsdaten: Wenn ein Turn nach einer zehnminütigen Pause weiterhin einen Cache-Lesezugriff ausweist, wurde ein Eintrag mit einer Gültigkeit von einer Stunde verwendet.

Beim OpenAI-kompatiblen Transport setzt Kunavo die Breakpoints für Claude-Modelle selbst – im System-Prompt, in den Tool-Definitionen und am Ende der Unterhaltung –, sobald der Prompt lang genug für das Caching ist, unabhängig davon, ob der Client eine Markierung sendet. GPT-Modelle werden vom jeweiligen Anbieter implizit zwischengespeichert.

Unabhängig davon, welche Seite die Breakpoints setzt, bleibt die Abrechnung gleich. Bei Claude Sonnet 5 kostet ein Cache-Lesezugriff $0.14 pro 1M Token, verglichen mit $1.40 für neue Eingaben. Ein Cache-Schreibzugriff kostet $1.75 — den Aufpreis, den Claude für das Schreiben gegenüber Eingaben berechnet; bei einem Eintrag mit einer Laufzeit von einer Stunde gilt derselbe Satz. Ein Eintrag bleibt fünf Minuten gültig, und jeder Lesezugriff verlängert seine Laufzeit. Was ein Agent bezahlt, hängt daher weniger vom Modell ab als davon, ob seine nächste Anfrage innerhalb dieses Zeitfensters eintrifft. Die Cache-Preise aller Modelle finden Sie auf der Seite zum Prompt-Caching.

Ein Verhalten von Hermes ist kostspieliger als jeder Preisunterschied: Laut Hermes-Dokumentation setzt ein Modellwechsel mitten in einer Sitzung, ein automatischer Fallback oder ein Wechsel der Anmeldedaten den Prompt-Cache zurück. Die nächste Nachricht liest dann die gesamte Unterhaltung erneut zum vollen Eingabepreis ein. Wählen Sie das Modell, bevor eine lange Sitzung beginnt.

Was ein ständig aktiver Agent pro Tag kostet

Bei Hermes werden auch dann, wenn niemand tippt, die von Ihnen geplanten Aufgaben und die Nebenaufgaben berechnet, die jede Unterhaltung auslöst. Laut der Cron-Dokumentation startet jeder geplante Lauf eine neue Sitzung. Daher wird bei jedem Lauf der gesamte Prompt berechnet – Anweisungen, Tool-Schemas und angehängte Skills. Die Größe dieses Prompts hängt von Ihrer Konfiguration ab; die Tabelle nennt deshalb ausdrücklich eine Annahme: 20.000 Tokens pro Lauf und ein Lauf alle 30 Minuten, also 48 pro Tag. Ersetzen Sie beide Werte durch Ihre eigenen.

Drei Einstellungen verändern diesen Wert; alle stammen aus der Hermes-Dokumentation. Ein geplanter Job verwendet sein jobeigenes Modell, andernfalls cron.model, andernfalls das Hauptmodell. Mit hermes config set cron.model claude-haiku-4-5 nehmen Sie also alle Jobs ohne festgelegtes Modell aus der teuren Modellstufe heraus. Ein Job-Skript, das {"wakeAgent": false} ausgibt, überspringt das Modell für diesen Lauf; ein Job ohne Agent ruft überhaupt kein Modell auf. Und die Nebenaufgaben – Komprimierung, Titel und Vision – laufen auf dem Hauptmodell, sofern auxiliary sie nicht an ein anderes Modell weiterleitet:

# ~/.hermes/config.yaml — what decides the cost of an unattended day
compression:
  threshold_tokens: 256000         # compact here, not at half of a 1M window

auxiliary:
  compression:
    provider: kunavo               # the named entry above
    model: claude-haiku-4-5        # summaries on the cheapest tier
  title_generation:
    provider: kunavo
    model: claude-haiku-4-5

threshold_tokens ist bei einem großen Kontextfenster entscheidend. Die Komprimierung beginnt standardmäßig bei der Hälfte der Kontextlänge. Laut Hermes-Dokumentation legt diese Einstellung eine feste Obergrenze für die Kosten eines einzelnen Aufrufs fest.

Die Stunden, in denen der Agent tatsächlich arbeitet, machen die andere Hälfte der Rechnung aus – und hier entscheidet der Cache. Nehmen wir 100 aufeinanderfolgende Anfragen, die jeweils einen Kontext mit 100.000 Tokens erneut senden, zusätzlich 2.000 neue Tokens enthalten und 800 Ausgabe-Tokens zurückgeben. Bei Claude Sonnet 5 sind das etwa $2.31, wenn der Kontext aus dem Cache gelesen wird, und etwa $14.84, wenn bei jeder Anfrage der Kontext als neue Eingabe abgerechnet wird. Gleiche Arbeit, dasselbe Modell: Der Unterschied besteht darin, ob die Breakpoints vorhanden sind und die Anfragen weniger als fünf Minuten auseinanderliegen.

Zur Einordnung, gemessen und nicht angenommen: Über die Kunavo-Konten hinweg, auf denen ein Agent dauerhaft läuft, hat ein aktiver Tag im Median $12.67 gekostet und ein Tag am 90. Perzentil etwa $163. Das sind Beträge, die bis 5. Oktober 2026 abgerechnet wurden, zu den jeweils an den betreffenden Tagen geltenden Tarifen. Es handelt sich um eine kleine Gruppe. Verstehen Sie diese Werte daher als Bandbreite, nicht als Prognose für Ihren Agenten.

Wenn das Guthaben aufgebraucht ist

Kunavo arbeitet mit Vorauszahlung: Jeder Aufruf wird aus dem Wallet bezahlt, und ein Agent, der arbeitet, während Sie schlafen, leert es, während Sie schlafen. Eine Anfrage, deren Kosten das Wallet nicht decken kann, wird auf beiden Übertragungswegen mit HTTP 402 und dem Code insufficient_balance abgelehnt; dafür wird nichts berechnet. Die Ablehnung erfolgt, bevor der Kontostand des Wallets null erreicht: Jede Anfrage reserviert zunächst ihre maximalen Kosten – den Prompt plus die größte zulässige Antwort. Je höher also die Ausgabebegrenzung ist, die ein Agent anfordert, desto früher werden seine Aufrufe abgelehnt. Der Fehler gibt an, wie viel gefehlt hat, in balance_usd und needed_usd.

Hermes Agent begegnet einem fehlschlagenden Anbieter mit einer Fallback-Kette: fallback_providers in config.yaml, verwaltet mit hermes fallback und der Reihe nach pro Turn durchlaufen. Laut Dokumentation lösen beim Hauptmodell Ratenbegrenzungen, Serverfehler, Authentifizierungsfehler und 404-Fehler den Fallback aus. Als Kapazitätsfehler, durch die eine Nebenaufgabe in der Kette zum nächsten Anbieter wechselt, wird auch HTTP 402 genannt. Was ein Turn bei HTTP 402 ohne konfigurierten Fallback tut, wird nicht erläutert. Gehen Sie von der naheliegenden Lesart aus: Der Turn schlägt fehl, ebenso ein geplanter Job. Beachten Sie außerdem, dass ein Turn, der auf einen anderen Anbieter zurückfällt, mit einem leeren Prompt-Cache beginnt.

Zwei Einstellungen schützen einen unbeaufsichtigten Agenten vor diesem Zustand, und sie erfüllen unterschiedliche Aufgaben:

• Automatisches Aufladen, unter Abrechnung. Speichern Sie eine Karte einmalig und legen Sie drei Werte fest: den Kontostand, unter dem Guthaben aufgeladen wird, den Betrag jeder Aufladung und ein monatliches Limit. Das Guthaben wird dann innerhalb von Sekunden nach einem Aufruf wieder aufgefüllt, durch den es unter den Schwellenwert fällt. Eine Anfrage, die eingeht, während das Guthaben noch nicht ausreicht, wartet auf diese Abbuchung und wird anschließend ausgeführt, statt abgelehnt zu werden. Ein 402 wird weiterhin zurückgegeben, wenn die Abbuchung nicht möglich ist — etwa weil die Karte abgelehnt wurde oder das Monatslimit erreicht ist — oder wenn eine Anfrage mehr Guthaben reserviert, als nach der Aufladung verfügbar ist. Dafür ist eine Karte oder Link erforderlich — Alipay, WeChat Pay, Pix und andere lokale Zahlungsmethoden können nicht automatisch belastet werden.
• Ein monatliches Limit für den Schlüssel, unter API-Schlüssel. Geben Sie dem Agenten einen eigenen Schlüssel und legen Sie den Höchstbetrag fest, den dieser Schlüssel in einem Kalendermonat ausgeben darf. Sobald dieser Betrag überschritten ist, werden seine Aufrufe mit einem 402 abgelehnt und es wird nichts berechnet, während Ihre anderen Schlüssel weiterhin funktionieren. Das ist die Obergrenze, die eine außer Kontrolle geratene Schleife braucht und die das Guthaben nicht bieten kann, da alle Schlüssel auf dasselbe Guthaben zugreifen.

Legen Sie den Schwellenwert fürs Aufladen höher fest als den Betrag, der für eine einzelne Anfrage reserviert wird. Bemessen Sie den Aufladebetrag am Tagesbedarf Ihres Agenten und nicht am Mindestbetrag: Die kleinste Aufladung beträgt $10, der zuvor genannte Median für einen Tag mit ständig aktivem Agenten $12.67. Die Limits für automatisches Aufladen finden Sie auf der Abrechnungsseite; den vollständigen Fehlerinhalt auf der Fehlerseite.

Verwandte Anleitungen

• Die benutzerdefinierte API von Hermes Agent – warum der ausgehende Provider nicht der eingehende API-Server ist, Erklärung des transport-Felds und Prüfungen für den ersten Aufruf.
• Preise von Hermes Agent – die Kosten für den Betrieb über die Tokenpreise hinaus.
• Zeitüberschreitung bei der Kontextkomprimierung von Hermes – was der Fehler bedeutet, wenn die Zusammenfassung hängen bleibt, und wie Sie den Vorgang wieder aufnehmen.
• Hermes im Vergleich zu OpenClaw – sowie dieselbe Konfiguration für den anderen Agenten auf der OpenClaw-Seite.