Benutzerdefinierte Hermes-Agent-API: Anbieter, Transporte und Prüfungen beim ersten Aufruf

Ein benutzerdefinierter Hermes-Agent-Endpunkt wird ausgehend konfiguriert, als benannter Eintrag unter providers: in ~/.hermes/config.yaml, wobei api die Basis-URL und transport das Übertragungsprotokoll ist. Das ist etwas anderes als Hermes' eigener API-Server, der in die andere Richtung zeigt. In Suchergebnissen werden beide als „Hermes custom API“ bezeichnet, und die offiziellen Dokumentationsseiten zu beiden ranken für dieselben Suchanfragen – klären Sie daher zuerst die Richtung.

Diese Seite handelt von Hermes Agent, dem Open-Source-Agenten von Nous Research. Eine Prüfung der GitHub-API am 21. September 2026 ergab archived: false, disabled: false, eine MIT-Lizenz und einen Push am selben Tag; die neueste veröffentlichte Version ist Hermes Agent v0.21.3, getaggt als v2026.9.14 am 14. September 2026, keine Vorabversion. Die Oberflächen, aus denen diese Seite Konfiguration bezieht, sind dieses Repository und hermes-agent.nousresearch.com. hermes-agent.org behandelt dasselbe Projekt von einer Domain außerhalb von nousresearch.com und lädt Microsoft-Clarity-Analysen (geprüft am 21. September 2026); sie gehört nicht zu den eigenen Oberflächen des Projekts. Übernehmen Sie daher keine Konfiguration von dort. Dies ist außerdem weder Hermes 3 noch Hermes 4, die Open-Weight-Modellfamilie von Nous, noch die gleichnamige JavaScript-Engine.

Zwei entgegengesetzte Dinge namens Hermes custom API

Beide Zeilen stammen aus Hermes' eigenen Seiten, gelesen am 21. September 2026: der Anbieterreferenz und der API-Server-Seite. Eine Namensbesonderheit sollten Sie in Ihrer eigenen Installation prüfen: Die API-Server-Seite dokumentiert hermes gateway als den Befehl, der ihn startet, während die CLI-Referenz hermes gateway als Manager des Messaging-Dienstes mit den Unterbefehlen run, start, stop und status beschreibt. Führen Sie hermes gateway --help aus, statt zu raten. Alles Folgende betrifft die ausgehende Hälfte.

Die minimale ausgehende Konfiguration

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com/v1   # aliases accepted: base_url, url
    key_env: KUNAVO_API_KEY          # or inline api_key:, or key_cmd:
    transport: chat_completions      # set it by hand; see the transport section
    models:
      claude-sonnet-5:
        prompt_caching: true

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

KUNAVO_API_KEY=your-key

Feld für Feld aus der Anbieterreferenz: Der Konfigurationsschlüssel ist providers.<name>, das Feld für die Basis-URL ist api (wobei base_url und url als Aliase akzeptiert werden), die Zugangsdaten sind key_env, ein Inline-api_key oder ein key_cmd, und das Protokoll ist transport. Derselbe Eintrag akzeptiert außerdem name, default_model, models, context_length, discover_models, extra_body, extra_headers, session_affinity_header, ssl_ca_cert / ssl_verify, catalog_provider und enabled: false. Wählen Sie den Eintrag mit model.provider: custom:kunavo oder während einer Sitzung mit /model custom:kunavo:<model-id> aus.

Zwei Befehle sind nicht austauschbar. hermes model wird außerhalb einer Chat-Sitzung ausgeführt, ist der vollständige Assistent zur Anbietereinrichtung und das einzige, was einen Anbieter hinzufügen oder einen Schlüssel übernehmen kann. /model innerhalb einer Sitzung wechselt nur zwischen bereits vorhandenen Einträgen. Für Enterprise-Endpunkte, die kurzlebige Token ausstellen, bezeichnet key_cmd einen Befehl, der ein Token auf stdout ausgibt — unverziert oder als JSON mit einem access_token-Feld — das Hermes ausführt und bis kurz vor dem Ablauf zwischenspeichert und das einen statischen api_key oder key_env am selben Eintrag übertrifft.

Wählen Sie den Transport manuell aus, statt das Feld leer zu lassen

Die Anbieterreferenz nennt drei zulässige Werte für transport bei einem benutzerdefinierten Eintrag. Sie besagt außerdem, dass der Assistent hermes model Custom Endpoint nun explizit nach dem Protokoll fragt und die Antwort in config.yaml speichert, und dass die URL-basierte automatische Erkennung „als Fallback weiterhin erfolgt, wenn das Feld leer gelassen wird“. Die einzige ausdrücklich dokumentierte Erkennungsregel ordnet einen /anthropic-Pfad anthropic_messages zu; eine Kunavo-Basis-URL entspricht dem nicht. Die übrige Heuristik wird auf keiner der hier gelesenen Seiten aufgelistet. Deshalb sollte das Feld geschrieben werden, statt zu erschließen, was geschehen würde. Kunavo stellt /v1/chat/completions, /v1/messages und /v1/responses bereit, sodass jeder Transport auf dem Papier eine passende Route hat.

Die Anthropic-Zeile verdient einen Vorbehalt statt einer selbstsicheren Antwort. Hermes' Azure-Foundry-Leitfaden erklärt, dass /v1 aus der Basis-URL entfernt wird, weil das Anthropic-SDK /v1/messages an jede Anfrage anhängt — dieser Satz steht jedoch unter einer Azure-Überschrift, und das eigene Beispiel der Anbieterreferenz (api: https://proxy.example.com/anthropic) sagt nicht, welches Suffix Hermes für einen generischen Proxy anhängt. Daher sind beide oben genannten Kandidaten plausibel, und einer davon könnte durch ein doppeltes /v1 im Pfad einen 404-Fehler erzeugen. Prüfen Sie den Anfragepfad, den Ihr erster Aufruf tatsächlich protokolliert; das Basis-URL-Dokument behandelt die Verwechslung zwischen Origin und /v1, die hinter den meisten 404-Fehlern bei dieser API-Verbindung steckt. Die Authentifizierung ist das kleinere Problem: Kunavos Messages-Route akzeptiert sowohl Authorization: Bearer als auch x-api-key, daher sollte der vom Anthropic-SDK an einen generischen Proxy gesendete Header akzeptiert werden — Hermes dokumentiert diese Wahl jedoch nicht, deshalb ist „sollte“ die ehrliche Formulierung.

Eine offene Frage, die auch diese Seite nicht beantworten wird. Hermes dokumentiert eine stille Aufwertung von GPT-5.x-Modellnamen zu codex_responses, selbst wenn config.yaml weiterhin chat_completions angibt — dieser Satz steht jedoch unter provider: azure-foundry und ist als Erkennung eines Modellnamens formuliert. Ob ein GPT-Slug auf provider: custom dieselbe Umstellung auslöst, ist nicht dokumentiert. Wenn Sie ein GPT-Klassenmodell auswählen, zeichnen Sie auf, an welche Route der erste Aufruf ging.

Was ein benutzerdefinierter Endpunkt je nach Transport nicht automatisch erhält

Keines davon ist eine Tarifgrenze. Hermes Agent ist laut der eigenen FAQ auf der Projekt-Homepage „kostenlos und unter der MIT-Lizenz als Open Source verfügbar“, und das providers:-Dict ist als gewöhnliche Konfiguration und nicht als Tarifmerkmal dokumentiert. Es handelt sich um Fähigkeitsgrenzen, die sich je nach Draht unterscheiden.

Zwei Auswege speziell für ein Gateway. catalog_provider akzeptiert eine Hermes-Anbieter-ID oder eine models.dev-ID und lässt die Modelle des Eintrags die Metadaten dieses Katalogs erben — nur für Abfragen; Anfragen gehen weiterhin an Ihre api-URL mit Ihrem Schlüssel. Und discover_models: false überspringt die /models-Prüfung vollständig und verwendet nur die Modelle, die Sie im Eintrag aufgelistet haben; das behebt Probleme bei lauter oder langsamer Erkennung. Ob Kunavos /v1/models-Antwort die Hermes-Prüfung erfüllt, wurde hier nicht getestet; falls nicht, fällt die Kontexterkennung auf den Standardwert 128K zurück. Die Kostenüberlegungen hinter diesen Einstellungen — Hilfsslots, Delegierungs-Worker und Cache-Kontinuität — stehen unter Hermes-Agent-Preise und werden hier nicht wiederholt.

Eine Prüfungsleiter, die Sie vor dem Einsatz echter Arbeit durchführen sollten

Dies sind Schritte, die Sie mit der erwarteten Beobachtung ausführen sollen, keine von Kunavo erhaltenen Ergebnisse. Es wurde kein Hermes-Lauf gegen Kunavo durchgeführt, es gibt keinen Kunavo-Einrichtungsleitfaden für Hermes, und nichts auf dieser Seite sollte als getestete Integration verstanden werden. Halten Sie Ihre funktionierende Route währenddessen verfügbar.

1. Fügen Sie den Anbieter hinzu und führen Sie anschließend die Diagnose aus. hermes model fügt ihn hinzu; hermes doctor ist als Diagnose von Konfigurations- und Abhängigkeitsproblemen dokumentiert, und die CLI-Referenz verzeichnet zwei Prüfungen der benutzerdefinierten Endpunktkonfiguration — einen custom_providers-Schlüssel, der keine YAML-Liste ist, und einen alten Listeneintrag ohne passenden providers:-Eintrag. Beide geben nur Warnungen aus, und --fix schreibt sie nicht um.
2. Bestätigen Sie, dass der Schlüssel geladen ist, bevor Kosten entstehen. hermes dump gibt eine kopierbare Einrichtungsübersicht aus — Version, Anbieter, Modell und ob ein API-Schlüssel vorhanden ist. Erwarten Sie Ihre Modell-ID und einen vorhandenen Schlüssel. hermes prompt-size läuft offline und meldet eine Byte-Aufschlüsselung des System-Prompts und der Tool-Schemas; dies ist der feste Teil, den jede Runde vor jedem Gesprächsinhalt mitführt.
3. Eine nicht gestreamte Text-Runde. Erwarten Sie eine Antwort und dass die Anfrage an den vorgesehenen Pfad gegangen ist. Ein benutzerdefinierter Endpunkt, der zwar „funktioniert“, aber unbrauchbare Daten zurückgibt, ist ein Eintrag in Hermes' Fehlerbehebungstabelle im Schnellstart. Dort werden eine falsche Basis-URL, ein falscher Modellname oder ein Endpunkt genannt, der tatsächlich nicht OpenAI-kompatibel ist; außerdem wird empfohlen, den Endpunkt zuerst in einem separaten Client zu überprüfen.
4. Eine gestreamte Runde. Erwarten Sie inkrementelle Ausgabe statt eines einzigen Blocks am Ende. Ob die Stream-Rahmung eines bestimmten Endpunkts Hermes' Fortschrittsanalyse erfüllt, wurde auf dieser Seite nicht getestet.
5. Eine Tool-Runde. Erwarten Sie, dass das Tool ausgeführt wird. Wenn der Aufruf stattdessen als Text ausgegeben wird, betrifft das die Tool-Calling-Unterstützung der bereitstellenden Seite, nicht den Transport.
6. Lesen Sie den Zähler ab. /usage ist das Sitzungsfenster für Token, Kosten und Kontext. Gleichen Sie es mit der Belastung ab, die Ihr Anbieter-Konto tatsächlich verzeichnet hat — die eigene Rechnung eines Agents über gemeldete Token ist eine Schätzung, kein Hauptbuch. Siehe das Nutzungsdokument.

Was die Prüfungsleiter kostet und was eine Umschaltung innerhalb der Sitzung kostet

Nehmen Sie an, dass die sechs obigen Schritte insgesamt 26.000 Eingabe-Token senden und 1.150 Ausgabe-Token empfangen — ein fester System-Prompt und ein Tool-Schema bei jedem von drei Aufrufen sowie ein einmal erneut gesendetes Tool-Ergebnis. Diese Annahme dient der Veranschaulichung; hermes prompt-size meldet Ihren eigenen festen Prompt als Byte-Aufschlüsselung, was der Wahrheit näherkommt als eine Zahl, die diese Seite schätzen könnte. Die Preise sind aktuelle Kunavo-Katalogpreise pro Million Token.

Dies ist veranschaulichende Token-Arithmetik zu Katalogpreisen, keine gemessene Hermes-Aufgabe und keine Rechnungsobergrenze. Cache-Schreibvorgänge, externe Tools und Steuern sind ausgeschlossen. Die Zahl soll ihre Geringfügigkeit zeigen: Das Überprüfen einer Route kostet weitaus weniger, als eine Fehlkonfiguration nach einer Woche geplanter Arbeit zu entdecken.

Die zweite Zahl ist diejenige, die der Befehl /model verbirgt. Prompt-Caches sind an das Modell gebunden, das die Anfrage verarbeitet. Daher führt jeder Modellwechsel während eines Gesprächs dazu, dass die nächste Nachricht das gesamte Gespräch zum vollen Eingabepreis erneut liest, statt zum Cache-Lesetarif; Hermes beschreibt diesen als ungefähr 75 bis 90 Prozent günstiger. Bei einem Gespräch mit 120.000 Token unter Verwendung von Claude Sonnet 5 beträgt der Unterschied zwischen $1.40 pro Million und dem $0.14-Cache-Lesetarif für diese eine Runde ungefähr $0.151 — einmalig unerheblich, als Gewohnheit jedoch nicht. Der Katalogbetrag von Kunavo ist eine Abrechnungsuntergrenze und keine Obergrenze: Wenn der Upstream seine Kosten meldet, entspricht der Rechnungsbetrag dem höheren der beiden Werte: den Katalogkosten oder den mit dem geltenden Aufschlag multiplizierten Upstream-Kosten. Die Mindestaufladung des Prepaid-Guthabens beträgt $10, ohne Abonnement. Siehe Abrechnung.

Die Konfiguration wieder zurücknehmen

Hermes dokumentiert einen Rückgängig-Pfad, weshalb ein Test mit geringem Risiko möglich ist. enabled: false im Eintrag blendet ihn aus, ohne ihn zu löschen. Zeitpunktbezogene Kopien von config.yaml werden vor hermes setup oder hermes migrate darin geschrieben und bei jeder Analyse in backups/config/config.yaml.<reason>.<timestamp> abgelegt; identische Wiederholungen werden übersprungen und nur die neuesten fünf pro Grund behalten. Wenn die Datei später nicht analysiert werden kann, verwendet Hermes die neueste funktionierende Kopie statt der integrierten Standardwerte. Die Konfigurationsreferenz kennzeichnet model.base_url außerdem als „bei Anbieterwechsel geleert“. Ein Wechsel zurück zu einem integrierten Anbieter ist daher als Entfernen der veralteten Basis-URL dokumentiert, statt sie in der Datei zu belassen — prüfen Sie den geschriebenen Wert anschließend, statt dies anzunehmen.

Drei Fallen stammen aus älteren Tutorials. Die alte Top-Level-Liste custom_providers: funktioniert weiterhin, und hermes update migriert sie automatisch in das providers:-Dict, wobei das alte model zu default_model und das alte api_mode zu transport wird. LLM_MODEL in .env wurde vollständig entfernt — config.yaml ist die einzige maßgebliche Quelle. Und OPENAI_BASE_URL wird von zwei aktuellen offiziellen Seiten auf zwei Arten dokumentiert: Die Anbieterreferenz sagt, dass es nur für den Anbieter openai-api berücksichtigt wird, während die Referenz der Umgebungsvariablen es als Basis-URL für einen benutzerdefinierten Endpunkt aufführt. Dieser Widerspruch ist ungelöst. Konfigurieren Sie den Endpunkt daher in config.yaml und verlassen Sie sich nicht auf diese Umgebungsvariable als Route.

Wenn Sie einen Anbieter auswählen statt einen einzurichten, erklärt OpenAI-kompatible API, was die kompatible Oberfläche umfasst und was nicht, und Hermes vs OpenClaw vergleicht die beiden Agents. Wenn Sie bereit sind, diese Route mit einem aufgeladenen Schlüssel zu testen, erstellen Sie ein Kunavo-Konto.

Häufig gestellte Fragen

Dokumentation zu Hermes Agent — Anbieterreferenz, API-Server-Seite, Modellkonfigurationsseite, Konfigurationsseite, CLI-Referenz, Slash-Befehlsreferenz, Schnellstart und Projekt-Homepage — gelesen am 21. September 2026. Repository-Status und neueste Veröffentlichung wurden am selben Tag anhand der GitHub-API geprüft. Kunavos drei API-Routen wurden im eigenen Quellcode bestätigt. Jede Dollarangabe ist veranschaulichende Token-Arithmetik über aktuelle Katalogpreise und keine gemessenen Aufgabenkosten. Die Hermes-Konfiguration stammt aus Quelldokumenten; es wurde kein Hermes-Lauf gegen Kunavo durchgeführt.