Interner Bonjour-Watchdog löst endlosen Gateway-Neustartloop bei systemd-Verwaltung aus - Bonjour Internal Watchdog Triggers Infinite Gateway Restart Loop Under systemd Management

Übersicht

Wenn der OpenClaw-Gateway gestartet und von einem systemd User-Service (openclaw-gateway.service) überwacht wird, tritt eine selbstdestruktive Neustartschleife des internen Bonjour mDNS-Watchdogs des Gateway-Prozesses ein. Der Watchdog erkennt kontinuierlich, dass der laufende Gateway sich im mDNS-Zustand probing statt announced befindet, interpretiert dies als Dienstausfall und ruft den ReAdvertisements-Pfad auf – was mit dem bereits laufenden Prozess kollidiert. Die Schleife wiederholt sich alle ~11 Sekunden und kann nicht unterbrochen werden, ohne den Gateway-Prozess zu beenden. Entscheidend ist, dass openclaw status durchgehend eine gesunde Ausgabe zurückgibt, was die Erkennung nicht-trivial macht.

Technische Manifestationen

1. Sich wiederholende Watchdog/Lock/Port-Fehler-Trias in den Logs (openclaw logs --follow):

2026-03-01T00:27:49Z warn  bonjour watchdog detected non-announced service; attempting re-advertise (state=probing)
2026-03-01T00:27:51Z error Gateway failed to start: gateway already running (pid 124904); lock timeout after 5000ms
2026-03-01T00:27:51Z error Port 18789 is already in use. pid 124904 ai-agent-naoki: openclaw-gateway (127.0.0.1:18789)

2026-03-01T00:27:60Z warn  bonjour watchdog detected non-announced service; attempting re-advertise (state=probing)
2026-03-01T00:27:62Z error Gateway failed to start: gateway already running (pid 124904); lock timeout after 5000ms
2026-03-01T00:27:62Z error Port 18789 is already in use. pid 124904 ai-agent-naoki: openclaw-gateway (127.0.0.1:18789)

2. Gleichzeitige gesunde Statusmeldung (Falsch-negativ – spiegelt den Zustellfehler nicht wider):

$ openclaw status
Gateway:  reachable
RPC:      ok
Port:     18789
PID:      124904
Uptime:   00:04:33

3. Cron-Jobs melden ok, aber die Zustellung wird stillschweigend verworfen:

$ openclaw cron list
ID          SCHEDULE     SESSION_TARGET  LAST_RUN              STATUS
──────────────────────────────────────────────────────────────────────
notif-001   */5 * * * *  main            2026-03-01T00:25:00Z  ok
notif-002   0 9 * * *    main            2026-03-01T00:00:00Z  ok

• Jobs mit sessionTarget: "main" werden erfolgreich ausgeführt, aber Discord/Webhook-Zustellungsnutzdaten werden stillschweigend verworfen.
• Jobs mit sessionTarget: "isolated" sind nicht betroffen.
• Das Deaktivieren der externen openclaw-watchdog.timer systemd-Einheit stoppt die Schleife nicht, was bestätigt, dass der Watchdog innerhalb des Gateway-Prozesses eingebettet ist.
• Die Schleife ist unabhängig vom tatsächlichen Netzwerk-/RPC-Zustand des Gateways aktiv.

4. systemd-Journal bestätigt den Neustartkonflikt auf OS-Ebene:

$ journalctl --user -u openclaw-gateway.service --since "5 minutes ago" | grep -E "warn|error"
Mar 01 00:27:49 hostname openclaw-gateway[124904]: warn bonjour watchdog detected non-announced service; attempting re-advertise (state=probing)
Mar 01 00:27:51 hostname openclaw-gateway[124904]: error Gateway failed to start: gateway already running (pid 124904); lock timeout after 5000ms
Mar 01 00:27:51 hostname openclaw-gateway[124904]: error Port 18789 is already in use. pid 124904 ai-agent-naoki: openclaw-gateway (127.0.0.1:18789)

Fehlerablauf

Der Defekt entsteht durch einen grundlegenden architektonischen Mismatch zwischen der Bonjour mDNS-Lebenszyklus-Zustandsmaschine und dem systemd-Prozess-Überwachungsmodell. Die folgende Sequenz beschreibt die vollständige Fehlerkette:

Phase 1 — mDNS-Probing-Phase wird auf Loopback niemals aufgelöst

Wenn der Gateway im Loopback-Modus startet (127.0.0.1:18789), bewirbt das Bonjour-Subsystem den Dienst über mDNS und tritt in den standardmäßigen Probe → Announce-Lebenszyklus ein. Auf einer Standard-Desktop-Netzwerkschnittstelle schließt das mDNS-Probing innerhalb weniger Sekunden ab, da der mDNS-Multicast-Stack keine widersprüchlichen Antworten empfängt und den Dienstdatensatz in den Zustand announced überführt.

Auf Loopback-Konfigurationen (127.0.0.1) werden die mDNS-Multicast-Probing-Pakete jedoch niemals über eine reale Netzwerkschnittstelle geroutet. Abhängig von der Multicast-Routing-Tabelle des Host-Kernels und dem Vorhandensein (oder Fehlen) einer aktiven Nicht-Loopback-Schnittstelle kann der mDNS-Stack im state=probing unbegrenzt steckenbleiben – der Probe schließt keine Konflikterkennung ab, weil keine Schnittstelle zum Multicasting verfügbar ist, und die Zustandsmaschine fällt nicht sicher auf announced als Standard zurück.

Phase 2 — Bonjour-Watchdog interpretiert probing falsch als Dienstausfall

Der interne Bonjour-Watchdog (läuft als wiederkehrendes Intervall innerhalb des Gateway-Prozesses, Periode ≈ 11 Sekunden) fragt den aktuellen mDNS-Werbungszustand ab. Die bedingte Logik des Watchdogs wertet aus:

if (mdnsServiceState !== 'announced') {
    logger.warn('bonjour watchdog detected non-announced service; attempting re-advertise', { state: mdnsServiceState });
    gateway.restart(); // ← löst vollständigen ReAdvertisements-Pfad aus
}

Der Watchdog unterscheidet nicht zwischen:

• probing (transient, erwarteter Vor-Ankündigungs-Zustand)
• conflict (echte mDNS-Namenskollision)
• failed (Werbeinfrastrukturfehler)

Alle Nicht-announced-Zustände werden als handlungsfähiger Ausfall behandelt, der einen Neustart erfordert, was für probing falsch ist.

Phase 3 — Re-Advertisements-Pfad erzeugt einen zweiten Gateway-Prozess

Der vom Watchdog verwendete gateway.restart()-Codepfad ruft nicht dieselbe PID/Lock-Erkennungslogik auf, die von openclaw gateway restart verwendet wird. Der CLI-Neustartbefehl liest korrekt die Lockdatei (typischerweise unter ~/.local/share/openclaw/gateway.lock oder entsprechendem XDG-Pfad), erkennt die Live-PID, sendet SIGTERM, wartet auf sauberen Exit und startet dann neu. Der interne Neustartpfad des Watchdogs umgeht diese Sequenz und versucht, Port 18789 zu binden und die Lockdatei direkt zu erwerben – was sofort fehlschlägt, weil der vorhandene Prozess beide hält.

Phase 4 — systemd Restart=always verstärkt den Effekt

Da openclaw-gateway.service mit Restart=always konfiguriert ist, ist systemd bereit, die Einheit bei jedem Exit neu zu starten. Der Gateway-Prozess selbst wird jedoch nicht beendet – der fehlgeschlagene Neustartversuch des Watchdogs wird intern behandelt und als Fehler protokolliert, aber der übergeordnete Prozess läuft weiter. Die Schleife läuft daher vollständig innerhalb der einzelnen PID 124904 und systemd beobachtet niemals einen Einheiten-Exit, was bedeutet, dass die eigene Neustartlogik von systemd nicht ausgelöst wird. Die Schleife ist vollständig selbst-contained innerhalb des Gateway-Prozesses.

Phase 5 — Stille Zustellfehler für main-Session-Jobs

Der Cron-Scheduler leitet die Job-Zustellung durch den Main-Session-Kanal, der auf dem internen Session-Bus des Gateways basiert. Die wiederholten fehlgeschlagenen Neustartversuche beschädigen oder setzen den Session-Bus-Zustand für main zurück, ohne den Prozess zu beenden. Jobs werden ausgeführt (Compute-Phase erfolgreich), aber die Zustellungs-Nutzlast-Versand über den Main-Session-Kanal wird verworfen, weil der interne Zustand des Kanals inkonsistent ist. Der Cron-Statusreporter liest nur das Ergebnis der Compute-Phase, nicht das Ergebnis der Zustellungsphase, und meldet ok. Jobs mit sessionTarget: "isolated" öffnen einen unabhängigen Session-Kanal pro Ausführung und sind daher nicht von dem beschädigten Main-Session-Zustand betroffen.

Sekundäres Problem: Fehlender delivery.mode-Standard für systemEvent-Nutzlasten

Jobs, die mit einem systemEvent-Nutzlasttyp erstellt wurden, erben keinen Standard-delivery.mode, was bedeutet, dass sie implizit auf den Main-Session-Kanal angewiesen sind. Diese Abwesenheit eines expliziten Zustellmodus macht es unmöglich, auf Konfigurationsebene zu unterscheiden, welche Jobs anfällig für Main-Session-Beschädigungen sind.

Die Behebungsstrategie hat drei Stufen: Sofortige Entlastung (Schleife stoppen), Strukturelle Lösung (mDNS/Loopback-Konflikt eliminieren) und Zustellungsresilienz (Cron-Jobs vor zukünftigen Session-Kanal-Problemen schützen).

Schritt 1 — Die aktive Schleife stoppen

Den Gateway-Dienst stoppen und maskieren, dann verifizieren, dass keine verwaisten Prozesse verbleiben:

# Stop the systemd service
$ systemctl --user stop openclaw-gateway.service

# Confirm the process is gone
$ pgrep -a -f openclaw-gateway
# Expected: no output

# If a stale process persists, force-kill it
$ kill -9 $(pgrep -f openclaw-gateway)

# Remove stale lockfile if present (path may vary by install)
$ rm -f ~/.local/share/openclaw/gateway.lock
$ rm -f /tmp/openclaw-gateway.lock

Schritt 2 — Den internen Bonjour-Watchdog über Gateway-Konfiguration deaktivieren

OpenClaw 2026.2.26 bietet kein dediziertes bonjour.watchdog.enabled-Flag in der öffentlichen API, aber der mDNS-Werbemodus kann überschrieben werden. Lokalisieren oder erstellen Sie die Gateway-Konfigurationsdatei:

# Default config location (XDG-compliant)
~/.config/openclaw/gateway.json

# Or project-local override
./.openclaw/gateway.json

Vorher:

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789
  }
}

Nachher:

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "bonjour": {
      "enabled": false,
      "watchdog": {
        "enabled": false
      }
    }
  }
}

• Das Setzen von bonjour.enabled: false deaktiviert die mDNS-Werbung vollständig. Dies ist sicher für Loopback-only-Deployments, wo mDNS-Diensterkennung weder benötigt noch funktional ist.
• Das Setzen von bonjour.watchdog.enabled: false deaktiviert explizit das interne Watchdog-Intervall und verhindert die Neustartschleife, selbst wenn bonjour.enabled versehentlich wieder aktiviert wird.
• Im Loopback-Modus (127.0.0.1) bietet Bonjour/mDNS keinen funktionalen Nutzen – kein anderer Host kann den Dienst über mDNS auf einer Loopback-only-Bindung erkennen.

Schritt 3 — Die systemd-Einheit aktualisieren, um das Konfig-Flag explizit zu übergeben

Stellen Sie sicher, dass die systemd-Diensteinheit die korrekte Konfiguration übergibt und eine explizite Überschreibung bereitstellt, selbst wenn die Konfigurationsdatei nicht gelesen wird:

# Edit the user service unit
$ systemctl --user edit openclaw-gateway.service

Fügen Sie die folgende Override-Stanza hinzu:

[Service]
Environment="OPENCLAW_GATEWAY_BONJOUR_ENABLED=false"
Environment="OPENCLAW_GATEWAY_BONJOUR_WATCHDOG_ENABLED=false"

Vollständige empfohlene Einheitenüberschreibung (~/.config/systemd/user/openclaw-gateway.service.d/override.conf):

[Unit]
Description=OpenClaw Gateway (systemd-managed, loopback)
After=network.target

[Service]
Restart=on-failure
RestartSec=5s
Environment="OPENCLAW_GATEWAY_BONJOUR_ENABLED=false"
Environment="OPENCLAW_GATEWAY_BONJOUR_WATCHDOG_ENABLED=false"
Environment="OPENCLAW_LOG_LEVEL=warn"

[Install]
WantedBy=default.target

• Geändert von Restart=always zu Restart=on-failure — verhindert, dass systemd den Gateway bei sauberen Exits neu startet (z.B. absichtliches openclaw gateway stop).
• Hinzugefügt RestartSec=5s, um schnelle Neustart-Stürme im Falle eines echten Absturzes zu verhindern.

Schritt 4 — Betroffene Cron-Jobs auf expliziten Zustellmodus migrieren

Für alle Cron-Jobs, die derzeit sessionTarget: "main" verwenden und auf Zustellung angewiesen sind (Discord-Benachrichtigungen, Webhooks usw.), migrieren Sie entweder zu sessionTarget: "isolated" oder fügen Sie einen expliziten delivery.mode hinzu:

Vorher (anfällige Konfiguration):

$ openclaw cron show notif-001
{
  "id": "notif-001",
  "schedule": "*/5 * * * *",
  "sessionTarget": "main",
  "payload": {
    "kind": "systemEvent",
    "event": "discord.notify"
  }
}

Nachher (resiliente Konfiguration — Option A: isolierte Session):

$ openclaw cron update notif-001 --session-target isolated

Nachher (resiliente Konfiguration — Option B: expliziter Zustellmodus):

$ openclaw cron update notif-001 --set delivery.mode=direct

Schritt 5 — Neu laden und Neustart

# Reload systemd daemon to pick up unit changes
$ systemctl --user daemon-reload

# Start the gateway
$ systemctl --user start openclaw-gateway.service

# Enable on login (if not already)
$ systemctl --user enable openclaw-gateway.service

Führen Sie die folgende Verifizierungssequenz nach der Anwendung aller Lösungsschritte durch. Jeder Befehl enthält die erwartete Ausgabe.

1. Bestätigen, dass der Gateway-Prozess mit der korrekten PID und ohne Duplikate läuft:

$ pgrep -c -f openclaw-gateway
1
# Expected: exactly 1 (one process, not two)

2. Bestätigen, dass die systemd-Einheit im Zustand active (running) ist:

$ systemctl --user is-active openclaw-gateway.service
active
# Expected exit code: 0

3. Bestätigen, dass der Gateway-RPC gesund ist:

$ openclaw status
Gateway:  reachable
RPC:      ok
Port:     18789
PID:      <pid>
Uptime:   <increasing value>
# Expected: no "unreachable" or "error" fields

4. Logs 60 Sekunden überwachen — Null-Wiederholung der Watchdog-Warn/Error-Trias bestätigen:

$ timeout 60 openclaw logs --follow | grep -E "bonjour watchdog|lock timeout|already in use"
# Expected: no output (zero matches)
# Exit code after timeout: 1 (grep found nothing — this is correct)

5. Bestätigen, dass der Bonjour-Watchdog im Journal unterdrückt wird:

$ journalctl --user -u openclaw-gateway.service --since "2 minutes ago" \
    | grep -c "bonjour watchdog"
0
# Expected: 0

6. Einen Cron-Job mit sessionTarget: "main" auslösen und Zustellung verifizieren:

# Force immediate execution of a cron job
$ openclaw cron run notif-001

# Verify delivery status (not just execute status)
$ openclaw cron show notif-001 --last-run
{
  "executedAt": "...",
  "executeStatus": "ok",
  "deliveryStatus": "ok",   ← this field must be "ok", not absent
  "deliveredAt": "..."
}

7. Verifizieren, dass Umgebungsvariablen im Service-Kontext aktiv sind:

$ systemctl --user show openclaw-gateway.service | grep Environment
Environment=OPENCLAW_GATEWAY_BONJOUR_ENABLED=false OPENCLAW_GATEWAY_BONJOUR_WATCHDOG_ENABLED=false

• Fehler: openclaw-watchdog.timer deaktivieren und annehmen, dass die Schleife stoppt.
  Die externe openclaw-watchdog.timer systemd-Einheit und der interne Bonjour-Watchdog sind separate Subsysteme. Das Maskieren der Timer-Einheit (systemctl --user mask openclaw-watchdog.timer) hat keinen Effekt auf das gateway-interne Intervall. Benutzer, die nur den Timer deaktivieren, werden weiterhin die Schleife sehen. Beide müssen unabhängig voneinander adressiert werden.
• Fehler: openclaw status als Proxy für die Zustellungsgesundheit prüfen.
  openclaw status prüft nur die RPC-Erreichbarkeit und die Prozesslebendigkeit des Gateways. Es testet nicht die Zustellungspipeline des Main-Session-Kanals. Ein Gateway kann vollständig reachable und RPC: ok sein, während er alle Main-Session-Zustellungen stillschweigend verwirft. Verwenden Sie openclaw cron show <id> --last-run und prüfen Sie das deliveryStatus-Feld explizit.
• Fehler: Restart=always in der systemd-Einheit maskiert Absturzschleifen.
  Mit Restart=always wird systemd den Gateway bedingungslos neu starten, einschließlich nach openclaw gateway stop (was sauber beendet). Dies führt zu Verwirrung, wo Betreiber glauben, sie hätten den Gateway gestoppt, aber er startet innerhalb von Sekunden erneut. Verwenden Sie Restart=on-failure für die Produktions-systemd-Verwaltung.
• Fehler: Loopback-only-Bindung (127.0.0.1) mit aktiviertem Bonjour.
  mDNS-Multicast-Pakete erfordern eine routingfähige Nicht-Loopback-Schnittstelle. Auf Systemen, die ausschließlich loopback-gebunden sind (z.B. CI-Runner, headless Server, VMs mit nur lo und einer privaten Schnittstelle), wird die mDNS-Probe-Phase niemals abgeschlossen. Der Gateway sollte automatisch dies erkennen und bonjour.enabled: false setzen, wenn host 127.0.0.1 oder ::1 ist, aber ab 2026.2.26 (bc50708) fehlt diese Erkennung.
• Fehler: ARM64 (aarch64)-Hosts und mDNS-Stack-Unterschiede.
  Das Problem wurde auf arm64 gemeldet (Ubuntu 24, Kernel 6.17.0-1008-nvidia). Einige ARM64-Ubuntu-Konfigurationen werden mit systemd-resolved ausgeliefert, das mDNS in einem Modus handhabt, der Multicast auf der Loopback-Schnittstelle aggressiver unterdrückt als x86_64-Konfigurationen. Der mDNS-probing-Zustand kann auf x86_64-Hosts mit aktiven LAN-Schnittstellen korrekt aufgelöst werden, was diesen Bug architektur- und netzwerktopologieabhängig macht.
• Fehler: delivery.mode fehlt bei systemEvent-Nutzlast-Jobs — keine Warnung ausgegeben.
  Cron-Jobs, die mit payload.kind: "systemEvent" erstellt wurden, erhalten keinen Standard-delivery.mode und geben keine Warnung über diese Auslassung aus. Diese Jobs werden stillschweigend vom Main-Session-Kanal abhängen. Auditen Sie alle systemEvent-Jobs: openclaw cron list --filter payload.kind=systemEvent | grep -v delivery.mode und fügen Sie explizite Zustellmodi hinzu.
• Fehler: Veraltete Lockdatei nach erzwungenem Kill verhindert sauberen Neustart.
  Wenn der Gateway-Prozess mit SIGKILL (statt SIGTERM) getötet wird, wird die Lockdatei unter ~/.local/share/openclaw/gateway.lock (oder /tmp/openclaw-gateway.lock je nach Installationstyp) möglicherweise nicht aufgeräumt. Nachfolgende Startversuche schlagen mit lock timeout after 5000ms fehl. Entfernen Sie die Lockdatei immer manuell nach einem erzwungenen Kill, bevor Sie neu starten.
• Fehler: macOS-Benutzer, die Avahi ausführen vs. Apple mDNS-Daemon-Unterschiede.
  Auf macOS wird Bonjour vom nativen mDNSResponder von Apple unterstützt, das Loopback-mDNS anders handhabt als Linux' avahi-daemon. Das beschriebene probing-Steckenbleiben ist spezifisch für Linux/Avahi-Umgebungen. macOS-Benutzer reproduzieren dieses Problem möglicherweise nicht, können aber eine verwandte Variante erleben, bei der mDNSResponder mit dem eingebetteten Bonjour-Stack des Gateways konfligiert, wenn beide versuchen, denselben Dienstnamen zu registrieren.
• Fehler: Docker-Container-Deployments, die den Host-Netzwerk-Namespace teilen.
  In Docker-Containern, die --network host verwenden, hängt das mDNS-Verhalten von der Schnittstellenkonfiguration des Hosts ab. Container, die Bridge- oder Overlay-Netzwerke verwenden, können Multicast vollständig unterdrücken und identische probing-Steckenbleiben-Symptome verursachen. Stellen Sie sicher, dass bonjour.enabled: false in allen containerisierten Deployments unabhängig vom Netzwerkmodus gesetzt ist.

• Gateway failed to start: gateway already running (pid XXXXX); lock timeout after 5000ms
  Ausgegeben, wenn der interne Neustartpfad des Watchdogs versucht, die Gateway-Lockdatei zu erwerben, während der vorhandene Prozess sie hält. Erscheint auch unabhängig, wenn ein Benutzer openclaw gateway start ausführt, während ein Gateway bereits läuft. Nicht immer ein Indikator für den Bonjour-Watchdog — prüfen Sie auf die vorausgehende bonjour watchdog detected non-announced service-Warnung, um das Schleifenszenario zu bestätigen.
• Port 18789 is already in use. pid XXXXX
  Ausgegeben unmittelbar nach dem Lockdatei-Timeout, wenn der sekundäre Startversuch versucht, den RPC-Port zu binden. Isoliert betrachtet kann dieser Fehler auch nach einem unsauberen Gateway-Herunterfahren erscheinen, das einen Socket im TIME_WAIT-Zustand hinterlässt. Verifizieren Sie mit ss -tlnp sport = :18789, ob der Port vom Gateway-Prozess oder einem anderen Prozess gehalten wird.
• bonjour watchdog detected non-announced service; attempting re-advertise (state=probing)
  Kernsymptom-Fehler. Kann auch transient erscheinen (einmal oder zweimal) bei legitimen Gateway-Neustarts, wenn der mDNS-Stack die Probe-Phase erneut betritt. Wird pathologisch nur, wenn es sich in einem Intervall wiederholt — bestätigen Sie mit Log-Zeitstempeln, dass die Periode ≈11 Sekunden beträgt.
• cron delivery failed: session channel unavailable (target=main)
  Ein sekundärer Fehler, der in ausführlichen Protokollierungsmodi erscheinen kann, wenn der Main-Session-Kanal in einem degradienten Zustand ist, der durch die Watchdog-Schleife verursacht wird. Wird bei Standard-Protokollierungsstufen nicht ausgegeben, weshalb Zustellungsfehler für die meisten Benutzer still erscheinen.
• RPC handshake timeout after 3000ms
  Kann erscheinen, wenn die Watchdog-Schleife einen momentanen internen Zustandsreset verursacht, während dem der RPC-Listener kurzzeitig nicht verfügbar ist. Unterscheidet sich vom primären Schleifenfehler, kann aber während hochfrequenter Watchdog-Zyklen in Logs eingestreut erscheinen.
• Historisch: mDNS-Namenskonflikt bei Multi-Instance-Deployments (vor-2025.8.x)
  In früheren Versionen verursachten mDNS-Namenskollisionen beim Ausführen mehrerer Gateway-Instanzen auf demselben LAN eine state=conflict-Variante derselben Watchdog-Warnung. Die Unfähigkeit des Watchdogs, probing von conflict zu unterscheiden, ist eine Fortsetzung derselben architektonischen Lücke.
• Historisch: openclaw-watchdog.timer Doppel-Neustart-Verstärkung (vor-2026.1.x)
  Bevor der externe Watchdog-Timer vom internen Gateway-Watchdog entkoppelt wurde, feuerten beide Timer unabhängig voneinander und verursachten bis zu zwei Neustartversuche pro ~11-Sekunden-Zyklus. Benutzer älterer Versionen können eine verdoppelte Fehlerfrequenz beobachten (ungefähr alle 5–6 Sekunden).