Hermes Agent mit Tailscale verbindet nicht: Lösungen

Das Tailnet Steht und Hermes Antwortet Immer Noch Nicht

Sie haben Tailscale auf dem VPS installiert, sind vom Laptop aus dem Tailnet beigetreten und haben bestätigt, dass sich beide Seiten auf ihren 100.x.x.x-Adressen anpingen. hermes serve läuft auf dem Host mit offenem Port, und die Hermes-Desktop-App auf dem Laptop dreht sich weiter auf "Could not connect to Hermes gateway." Nichts im Gateway-Log wirkt böse. Nichts in Tailscale ist rot.

Dieses stumme Versagen liegt fast immer an einer von vier Ursachen, und drei davon versagen bauartbedingt still. Dieser Beitrag geht jede durch, wie Sie feststellen, welche Ihre ist, und den genauen Fix. Beginnen Sie oben: Die erste Ursache erwischt die Mehrheit der frisch aufgesetzten Remote-Setups, und jede weitere Ursache setzt voraus, dass die vorherigen ausgeschlossen sind.

Ursache 1: hermes serve Ist an 127.0.0.1 Gebunden

hermes serve bindet sich standardmäßig an 127.0.0.1. Das ist der richtige Standard für ein reines Laptop-Setup und der falsche für alles, was Sie über das Tailnet erreichen wollen. Ein an das Loopback gebundener Prozess beantwortet nur Anfragen, die von derselben Maschine kommen, und ein Tailscale-Peer ist nicht dieselbe Maschine. Der Port ist offen, die Firewall ist in Ordnung, der Tunnel steht, und der Socket lehnt die Verbindung ab.

Symptom: Vom Laptop aus gibt curl -v http://<hermes-vps>:8642/api/health Connection refused zurück oder hängt bis zum Timeout. Aus einer SSH-Sitzung auf dem VPS antwortet dasselbe curl http://127.0.0.1:8642/api/health sofort. Wenn Loopback antwortet und das Tailnet nicht, ist das Ihre Ursache.

Der Fix besteht darin, hermes serve explizit an die Tailscale-IP des Hosts zu binden:

TAILSCALE_IP=$(tailscale ip -4)
hermes serve --host "$TAILSCALE_IP" --port 8642

Auf das Tailnet-Interface zu binden statt auf 0.0.0.0 ist die Form, die Sie wollen. 0.0.0.0 funktioniert auch und wird in vielen Anleitungen empfohlen, exponiert den Socket aber auf jeder Schnittstelle, die die Maschine hat, einschließlich einer versehentlich öffentlichen, und legt die gesamte Authentifizierungsgeschichte wieder auf die Anwendungsebene. An die Tailscale-IP zu binden ist Verteidigung in der Tiefe: Der Socket ist überhaupt nur von innerhalb des Tailnets erreichbar.

Machen Sie die Änderung dauerhaft, indem Sie dasselbe Flag in die Systemd-Unit oder in das command der docker-compose.yml schreiben. Wenn Sie in Docker laufen, veröffentlichen Sie den Port direkt an der Tailscale-IP mit -p ${TAILSCALE_IP}:8642:8642 statt des standardmäßigen -p 8642:8642 (das auf jeder Host-Schnittstelle veröffentlicht).

Für die vollständige Erstinstallation mit Tailscale geht die Anleitung für sicheren Remote-Zugriff mit Hermes Agent + Tailscale das Rezept von Anfang bis Ende durch.

Ursache 2: Der CORS-Regex des Dashboards Lehnt Ihre Tailscale-Origin Ab

Sie binden das Gateway an die Tailscale-IP, die API antwortet auf /api/health, und das Web-Dashboard lädt sein HTML von http://<hermes-vps>:8642/. Danach schlägt jeder API-Aufruf, den das Dashboard macht, mit einem CORS-Fehler in der Browser-Konsole fehl: has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

Was passiert: Ältere Hermes-Builds lieferten einen hartcodierten allow_origin_regex im Dashboard, der nur ^https?://(localhost|127\.0\.0\.1)(:\d+)?$ traf. Der Regex war auf einem Laptop sicher und überall sonst still unbrauchbar. Ein Tailscale-Hostname wie http://hermes-vps:8642 oder eine IP wie http://100.64.1.5:8642 trifft nie, also scheitert der Preflight und der Browser verwirft den Fetch. Der Feature Request, der den Fix verfolgt, hat die vollständige Historie.

Der Fix ist eine Umgebungsvariable:

export HERMES_DASHBOARD_CORS_ORIGINS="http://hermes-vps:8642,http://100.64.1.5:8642"
hermes serve --host "$TAILSCALE_IP" --port 8642

Listen Sie jede Origin auf, von der Sie das Dashboard tatsächlich laden: den MagicDNS-Namen, die rohe Tailscale-IP und jeden Funnel- oder Serve-Alias, den Sie hinzugefügt haben. Wildcards werden unterstützt (http://*.tail1a2b3.ts.net:8642), wenn Sie lieber den ganzen Tailnet-Namen matchen möchten, statt jedes Gerät aufzuzählen.

Zwei verwandte Stellschrauben, an denen Leute stolpern:

HERMES_DASHBOARD_HOST überschreibt die Adresse, die das Dashboard dem Browser bekannt gibt. Wenn Sie sie auf localhost gelassen haben, rendert das Dashboard Links zurück zu http://localhost:8642/api/..., und der Browser versucht, sein eigenes Loopback statt das Tailnet zu treffen. Setzen Sie sie auf Ihren Tailscale-Hostnamen oder Ihre IP.
Die Hermes-Desktop-App trägt ebenfalls eine Origin. Wenn Sie das gepackte Desktop statt des Browser-Dashboards nutzen, sendet dessen Renderer Origin: null (Electron lädt über file://). Ältere Builds akzeptierten das nur, wenn der Server an das Loopback gebunden war, was die in Issue #38412 beschriebene wechselseitige Exklusivität ist. Aktuelle Builds akzeptieren null, wenn es in HERMES_DASHBOARD_CORS_ORIGINS neben Ihren echten Origins steht: Fügen Sie den literalen String null zur Liste hinzu, um den Desktop-Client zuzulassen.

Starten Sie hermes serve nach jeder Änderung dieser Env-Vars neu. Die Werte werden beim Start gelesen, nicht pro Request.

Ursache 3: Der Tailscale-Tunnel Fällt auf DERP Zurück oder Kommt Gar Nicht Hoch

Wenn das Dashboard schließlich lädt, aber jede Nachricht mehrere Sekunden zum Senden braucht und Sprachnotizen stottern, steht der Tunnel, aber langsam. Tailscale relayt jedes Paket über einen DERP-Server bis zu Ihrem VPS, und die Round-Trip-Zeit wird von diesem Extra-Hop dominiert statt vom Modell. Wenn gar nichts durchkommt, ist der Tunnel wahrscheinlich nie hochgekommen.

Bestätigen Sie, welchen Fall Sie haben, mit tailscale status. Ein gesunder Peer zeigt direct <ip>:<port> in seiner Zeile. Ein per DERP relayter Peer zeigt relay "<region>". Wenn der Peer ganz fehlt oder als offline markiert ist, ist der Tunnel nie zustande gekommen.

Der Fix unterscheidet sich je nach Fall:

In DERP hängengeblieben. Öffnen Sie UDP 41641 ausgehend sowohl an der Host-Firewall des VPS als auch an der Netzwerk-Firewall des Clients. Das ist der Port, den Tailscale für direkte WireGuard-Tunnel verwendet; wenn eine Seite ausgehendes UDP blockiert, fallen beide Peers auf DERP zurück, auch wenn das Paar authentifiziert ist. Bestätigen Sie mit sudo ufw allow 41641/udp auf dem VPS und pingen Sie den Peer nach tailscale down && tailscale up erneut an. Firmennetze und Hotel-WLAN sind die üblichen Verdächtigen, die ausgehendes UDP blockieren. Wenn eine direkte Verbindung unmöglich bleibt, funktioniert DERP für Text, aber Sie werden es bei Sprache spüren.
Peer als offline markiert oder Tunnel nie hochgekommen. Der Node-Key ist abgelaufen. Tailscale rotiert Keys standardmäßig alle 180 Tage, und ein Gerät, das während des Rotationsfensters offline war, kommt in der Admin-Konsole als "offline" zurück, bis Sie sich neu authentifizieren. Beheben Sie das mit tailscale up --force-reauth auf der betroffenen Seite und melden Sie sich per Browser neu an. Um die Rotation bei serverseitigen VPS-Installationen ganz zu vermeiden, taggen Sie den Node (tailscale up --advertise-tags=tag:server) und deaktivieren Sie den Key-Ablauf für diesen Tag in der Tailscale-Admin-Konsole: Getaggte Nodes überspringen die 180-Tage-Prüfung standardmäßig.
Der Batteriesparmodus hat den Client auf dem Laptop abgeschossen. macOS und Windows lassen das Betriebssystem Hintergrunddienste in aggressiven Energiemodi anhalten, und die Tailscale-Menüleisten-App kann sich still selbst abmelden. Wenn das Tailnet gleich nach dem Abziehen des Netzsteckers dunkel wurde, schauen Sie zuerst auf das Tray-Symbol, bevor Sie irgendetwas anderes diagnostizieren.

Ursache 4: Sie Greifen von einem Remote-Client aus auf eine Localhost-URL Zu

Der letzte stille Fall ist der, in dem jede Ebene funktioniert und der Client die falsche Frage stellt. Wenn Sie die Remote Gateway URL von Hermes Desktop als http://localhost:8642 oder http://127.0.0.1:8642 konfiguriert haben, versucht die App, ihr eigenes Loopback-Interface zu erreichen, statt das Tailnet zu überqueren, und kein serverseitiger Fix wird helfen.

Symptom: Auf dem Laptop zeigt die Desktop-App "Could not connect." Von demselben Laptop aus antwortet curl http://<hermes-vps>:8642/api/health gesund.

Der Fix ist eine einzige Einstellung. Öffnen Sie in Hermes Desktop Settings, dann Connection, und setzen Sie die Remote Gateway URL auf eine von:

http://<magic-dns-name>:8642 - bevorzugt, übersteht Tailscale-IP-Änderungen.
http://<tailscale-ip>:8642 - die rohe 100.x.x.x-Adresse. Stabil genug für ein statisches Setup.

Der MagicDNS-Name ist das, was tailscale status in der ersten Spalte für die VPS-Zeile anzeigt. Wenn Sie MagicDNS nie aktiviert haben, tun Sie es in der Admin-Konsole unter DNS: Es ist ein einzelner Toggle und erspart Ihnen jede IP-Wechsel-Debug-Sitzung für die gesamte Lebensdauer des Tailnets.

Solange Sie in Settings sind, prüfen Sie das Credentials-Feld. Wenn das Gateway hinter einem Token liegt (HERMES_AUTH_TOKEN), braucht der Client dasselbe Token, und ein veraltetes erzeugt einen 4403 auf dem WebSocket, der einem Verbindungsfehler sehr ähnelt. Das Issue zum WebSocket 4403 hat mehr Details zu diesem konkreten Fehlerbild.

Diagnosereihenfolge, die Zeit Spart

Wenn das Tailnet steht und Hermes nicht antwortet, arbeiten Sie die Ursachen in dieser Reihenfolge ab, statt Ihr Tailscale-Setup neu aufzubauen:

Ist hermes serve an Loopback gebunden? curl http://<tailscale-ip>:8642/api/health vom Client beantwortet das in einer Sekunde. Höchste Trefferquote bei frisch aufgesetzten Remote-Setups.
Lehnt der CORS-Regex des Dashboards Ihre Origin ab? Öffnen Sie die Browser-DevTools auf dem Dashboard und suchen Sie einen roten CORS-Eintrag im Netzwerk-Tab. Wenn er vorhanden ist, setzen Sie HERMES_DASHBOARD_CORS_ORIGINS und starten Sie neu.
Ist der Tunnel direkt oder relayed? tailscale status zeigt pro Peer direct oder relay. Offline bedeutet, dass der Node-Key abgelaufen ist und Sie --force-reauth brauchen.
Fragt der Client nach localhost? Öffnen Sie die Verbindungseinstellungen der Desktop-App und bestätigen Sie, dass die Remote Gateway URL auf den Tailnet-Hostnamen zeigt, nicht auf localhost.

Für das darunterliegende Docker-Rezept auf dem VPS siehe die Hermes-Agent-Docker-Anleitung. Wenn Sie das Mesh ganz überspringen möchten, deckt Selbst-Hosting vs. verwaltetes Hermes Agent die Kompromisse ab.

Wenn Sie Lieber Kein Mesh Betreiben Möchten

Tailscale ist die richtige Form für ein selbst gehostetes Hermes, wenn Sie die Kiste auf Ihrem eigenen VPS halten und sie von überall erreichen wollen. Es ist auch ein zusätzliches System, das am Leben gehalten werden will: ein Key-Rotationsfenster, eine CORS-Env-Var, eine Firewall-Regel für UDP 41641 und eine Client-Einstellung, die mit dem Tailnet-Namen des Tages übereinstimmen muss. Wenn Ihr Fazit lautet, dass ein persönlicher KI-Agent kein Mesh-VPN und keine Debug-Sitzung in der Browser-Konsole brauchen sollte, um Hallo zu sagen, starten Sie mit Hermify. Hermify betreibt einen verwalteten Hermes Agent auf Telegram mit demselben Gedächtnis und denselben Skills, in etwa einer Minute live, ohne offene Ports und ohne Tailnet, das gepflegt werden will.