Hermes Agent mit DeepSeek: Häufige Fehler beheben

Suchen Sie in der Tabelle nach Ihrem Problem und lesen Sie den zugehörigen Abschnitt. Heben Sie die ursprüngliche Fehlermeldung auf. So können Sie nach jeder Änderung vergleichen, ob der Fehler behoben wurde oder sich nur die Meldung geändert hat.

Wenn die Installation mit einer Fehlermeldung abbricht, beheben Sie zuerst die dort genannte Ursache. Ist die Installation abgeschlossen, aber der Befehl hermes wird nicht gefunden, öffnen Sie ein neues Terminal und prüfen Sie den Programmpfad. Unter macOS oder Linux verwenden Sie command -v hermes, in PowerShell Get-Command hermes.

Verwenden Sie den aktuellen offiziellen Installer für Ihr Betriebssystem. Falls Sie Hermes über einen nicht unterstützten Paketmanager installiert haben, installieren Sie nicht wahllos weitere Varianten darüber. Erhalten Sie bei der Reparatur Ihr Hermes-Datenverzeichnis, damit Ihre Sitzungen und Einstellungen nicht verloren gehen.

Sobald der Befehl hermes funktioniert, führen Sie die folgenden Diagnosebefehle aus. Prüfen Sie deren Ausgabe, bevor Sie sie weitergeben, und entfernen Sie vertrauliche Angaben. Die Berichte können lokale Pfade und Konfigurationsdetails enthalten.

Antwortet die direkte DeepSeek-API mit Status 401, prüfen Sie, ob API-Schlüssel und Zieladresse zusammenpassen. Geben Sie Ihren DeepSeek-API-Schlüssel über hermes model oder die Anbietereinstellungen in Hermes Desktop erneut ein. Achten Sie auf Kopierfehler und prüfen Sie, ob der Schlüssel noch gültig ist.

Haben Sie den Schlüssel von einem anderen Dienst erhalten, verwenden Sie den von diesem Dienst angegebenen Endpunkt. Ein solcher Schlüssel funktioniert nicht automatisch an api.deepseek.com. Fehlt der gewünschte Anbieter in der Modellauswahl, richten Sie zuerst seine Zugangsdaten ein und öffnen Sie die Auswahl erneut.

Testen Sie die Verbindung anschließend in einem neuen Chat mit einer kurzen Anfrage. Scheitert auch dieser Test, prüfen Sie, ob der Chat tatsächlich den gerade eingerichteten Anbieter und das richtige Profil verwendet. Geben Sie in einer Supportanfrage weder Ihren API-Schlüssel noch Ihre vollständige .env-Datei oder eine config.yaml mit vertraulichen Angaben weiter.

Bei Status 404 oder einer Meldung wie model not found prüfen Sie sowohl die URL als auch die genaue Modell-ID. Entnehmen Sie die ID der Modellliste Ihres Anbieters; der Anzeigename in einem Artikel muss nicht der gültigen API-Bezeichnung entsprechen. DeepSeeks Hermes-Anleitung verwendet für die direkte Verbindung https://api.deepseek.com und nennt deepseek-v4-pro als Beispiel.

Bei einem benutzerdefinierten Anbieter muss außerdem der API-Modus stimmen. Chat Completions, Responses und Anthropic Messages erwarten unterschiedliche Anfrageformate. Verwenden Sie deshalb URL, Modell-ID und API-Modus aus derselben Anleitung für Ihren Anbieter.

Bei DeepSeek bedeutet Status 400, dass das Format der Anfrage ungültig ist; Status 422 weist auf ungültige Parameter hin. Suchen Sie in der Fehlermeldung nach dem betroffenen Feld und korrigieren oder entfernen Sie diese Einstellung. Testen Sie danach zunächst einen einfachen Chat, bevor Sie weitere Parameter oder Tools hinzufügen.

Sehen Sie zuerst nach, worauf Hermes wartet. Läuft noch eine Modellanfrage oder ein Tool-Aufruf? Muss ein Datei- oder Terminalzugriff erst von Ihnen freigegeben werden? Wenn eine Freigabe aussteht, hilft es nicht, dieselbe Anfrage erneut zu senden.

Starten Sie einen neuen Chat mit der kurzen Anfrage unten. Erhalten Sie auch dort keine Antwort, prüfen Sie die Netzwerkverbindung, gegebenenfalls den Proxy und die konfigurierte Serveradresse. Führen Sie außerdem hermes doctor aus. Funktioniert der kurze Chat, untersuchen Sie bei der ursprünglichen Aufgabe den Tool-Aufruf, bei dem der Ablauf stehen geblieben ist.

Geben Sie in einem Fehlerbericht an, wie lange Sie gewartet haben. Nennen Sie außerdem Hermes-Version, Betriebssystem, Anbieter und Modell-ID und fügen Sie die Fehlermeldung ohne vertrauliche Angaben hinzu. Senden Sie die vollständige Aufgabe nicht erneut, solange die vorherige Anfrage noch läuft. Auch der kurze Verbindungstest kann API-Kosten verursachen.

Eine funktionierende Modellverbindung sagt noch nichts darüber aus, ob die benötigten Tools eingerichtet sind. Öffnen Sie hermes tools oder die Tool-Einstellungen in Hermes Desktop und prüfen Sie, ob das Tool für die verwendete Oberfläche aktiviert ist. Meldet das Tool ein fehlendes Zusatzprogramm, fehlende Zugangsdaten oder unzureichende Berechtigungen, beheben Sie die dort genannte Ursache.

Bitten Sie Hermes, die Dateien in einem kleinen Testordner aufzulisten. Prüfen Sie in der Anzeige der Tool-Aufrufe, ob das Datei-Tool tatsächlich ausgeführt wurde und erfolgreich war. Funktioniert der Dateizugriff, aber die Websuche nicht, prüfen Sie die Einrichtung des Suchanbieters, bevor Sie den DeepSeek-API-Schlüssel ändern.

Wählen Sie in hermes tools den Bereich Web Search & Extract. Prüfen Sie dort, welcher Anbieter ausgewählt ist und welche Zugangsdaten oder Serveradresse er benötigt. Manche Anbieter erlauben auch den Zugriff ohne API-Schlüssel. Suche und Abruf einer Webseite lassen sich getrennt konfigurieren: Eine erfolgreiche Suche bedeutet deshalb noch nicht, dass Hermes die gefundenen Seiten öffnen kann. Testen Sie beides nacheinander mit einer kurzen Suchanfrage und einem der gefundenen Links. Der Suchdienst kann dafür eigene Gebühren berechnen.

Wenn Sie Hermes mit Blank Slate eingerichtet haben, sind viele Funktionen zunächst deaktiviert. Aktivieren Sie die Tools, die Sie für die Aufgabe benötigen, und lassen Sie die Freigabeabfragen während des Tests eingeschaltet. Sie können damit nachvollziehen, welche Aktionen anstehen. Das Abschalten der Abfragen hilft weder bei einem fehlenden Tool noch bei einem inkompatiblen Modell.

Die folgende Tabelle erklärt die Statuscodes der direkten DeepSeek-API. Wenn Sie einen Coding Plan über ein Gateway nutzen, können zusätzliche Nutzungslimits gelten. Prüfen Sie in diesem Fall auch die Fehlermeldung und die Verbrauchsanzeige des Gateway-Anbieters, bevor Sie Guthaben nachladen oder den Anbieter wechseln.

Prüfen Sie in Hermes Desktop unter Settings → Applies to, für welches Profil Sie die Einstellungen bearbeiten. Vergleichen Sie das mit dem im Chat ausgewählten Modell. Wenn Sie das Standardmodell eines Profils ändern, kann ein bereits geöffneter Chat weiterhin das zuvor gewählte Modell verwenden. Starten Sie deshalb einen neuen Chat und wählen Sie das gewünschte Modell für den Test ausdrücklich aus.

CLI und Desktop verwenden nur dann dieselben gespeicherten Einstellungen und Sitzungen, wenn sie mit demselben Hermes-Datenverzeichnis und Profil auf demselben Backend arbeiten. Eine native Windows-Installation und eine WSL-Installation haben getrennte Datenverzeichnisse. Ist Desktop mit einem entfernten Rechner verbunden, müssen Sie die Einstellungen dort ändern. Eine lokal bearbeitete Datei wirkt sich auf diese Verbindung nicht aus.

Mit hermes profile list sehen Sie, welche Profile vorhanden sind. Sichern Sie eine Konfigurationsdatei, bevor Sie sie direkt bearbeiten, und starten Sie anschließend den Hermes-Prozess neu, der sie verwendet. Löschen Sie zur Fehlerbehebung nicht das gesamte Datenverzeichnis; ändern Sie gezielt die betroffene Einstellung.

Wenn DeepSeek im Thinking-Modus Tools aufruft, muss der Agent beim erneuten Senden des bisherigen Chatverlaufs die von der API verlangten Reasoning-Felder mit übermitteln. Ein Fehler zu reasoning_content kann daher daran liegen, wie Hermes oder ein Gateway den Verlauf zusammenstellt. Der API-Schlüssel kann trotzdem gültig sein.

Im Hermes-Issue #15679 wurde ein solcher Fehler im April 2026 gemeldet. Das Issue wurde geschlossen, nachdem ein Mitwirkender auf eine Korrektur hingewiesen hatte. Daraus lässt sich nicht ableiten, dass Ihre aktuelle Version denselben Fehler hat. Notieren Sie Ihre Hermes-Version und aktualisieren Sie das Programm mit der für Ihre Installation vorgesehenen Methode. Vergleichen Sie danach einen neuen Chat mit der betroffenen Sitzung.

Funktioniert der neue Chat, während der alte weiterhin fehlschlägt, bewahren Sie die ursprüngliche Sitzung auf. Beschreiben Sie mit möglichst wenigen Schritten, wie sich der Fehler auslösen lässt, und melden Sie dies je nach Verbindungsweg bei Hermes oder Ihrem Gateway-Anbieter. Entfernen Sie zuvor vertrauliche Daten. Bearbeiten Sie gespeicherte Gesprächsfelder nicht auf Grundlage eines alten Issue-Kommentars und löschen Sie Ihren Verlauf nicht.