Kein Fehler bremst ein OpenClaw-Gateway-Rollout härter aus als Error: listen EADDRINUSE: address already in use. Im Jahr 2026 verwechseln Teams weiterhin „Port belegt“ mit „Modell-API down“, rotieren API-Schlüssel stundenlang und übersehen, dass ein Zombie-node vom gestrigen Smoke-Test noch TCP 8787 hält. macOS verkompliziert die Lage: launchd startet Jobs neu, bevor der alte Socket vollständig abgebaut ist, mehrere Profile teilen sich einen gemieteten Mac mini, und synthetische Health-Checks curlen oft 127.0.0.1, während das Gateway an eine LAN-Adresse bindet. Dieser Leitfaden liefert eine wiederholbare Triage—zuerst lsof, dann Plist-Parität, dann Probe-Ausrichtung—und verknüpft sie mit Doctor-Gateway-Diagnose, Erststart-Smoke-Tests für LaunchAgent und Gateway-Health-Monitoring, damit Betrieb nicht rät.
Portkollisionen sind Kapazitätsvorfälle: dokumentieren Sie Schnittstelle, PID und zuletzt verwendetes LaunchAgent-Label, damit Postmortems kurz bleiben.
Wenn Sie Blue/Green ohne Portbuch fahren, enden Wochenend-Deployments regelmäßig mit zwei Instanzen auf derselben Zahl—planen Sie deshalb Bandbereiche und Besitzer im Wiki.
Symptome wie Upstream-Ausfälle
Klienten sehen Verbindungsabbrüche, leere curl-Antworten oder Dashboards mit „Gateway offline“, obwohl die CPU müßig ist. Bevor Sie Modellanbieter beschuldigen, prüfen Sie, ob der HTTP-Server jemals LISTEN erreichte. Stirbt der Prozess beim Start, kann stderr enden, bevor ein Banner erscheint—nur errno bleibt. Sammeln Sie StandardErrorPath-Ausgaben und korrelieren Sie mit launchctl print-Zustandswechseln.
Bei geteilten gemieteten Mac minis sind verwaiste npm run dev-Sessions der Hauptverdächtige; sie tauchen selten in Grafana auf, weil sie nie Metriken registrierten.
DNS-Fehler und TLS-Handshake-Probleme erzeugen ähnliche Symptomwolken—deshalb zuerst Socket, dann TLS, dann Upstream.
lsof-Rezepte unter einer Minute
lsof -nP -iTCP:8787 -sTCP:LISTEN-n vermeidet langsame DNS-Lookups; -P zeigt numerische Ports. Steht ein fremder node-PID, sichern Sie vor dem Kill ps -p PID -o args=. Wenn nichts lauscht, klienten aber scheitern, prüfen Sie HTTPS-vs-HTTP-Mismatch auf derselben Portnummer.
Für IPv6-only-Listener hilft lsof -nP -i6TCP:8787; Dual-Stack-Sockets können doppelt erscheinen.
LaunchAgent ProgramArguments und Port-Flags
Doppelte --port-Angaben aus Wrapper und Template überschreiben sich still. Halten Sie eine Quelle: entweder EnvironmentVariables oder explizite Argumente. Nach Änderungen launchctl bootout und bootstrap, damit der alte Socket schließt, bevor der neue Job startet.
WorkingDirectory muss zum Checkout mit der erwarteten package.json zeigen; falsches cwd plus npx erzeugt leicht einen zweiten Listener auf dem Default-Port.
127.0.0.1 versus 0.0.0.0 versus LAN-IP
Loopback schützt vor simplen LAN-Scans, bricht aber Health-Checks von anderen Hosts. 0.0.0.0 akzeptiert alles und verlangt Firewall-Disziplin. Feste Büro-IP kollidiert mit DHCP-Renewals. Dokumentieren Sie den Vertrag im Runbook und spiegeln Sie ihn in openclaw doctor-Erwartungen.
Health-Probes, die lügen
Synthetische Monitore, die curl http://127.0.0.1:8787/readyz ausführen, bleiben grün, während Remote-Nutzer 10.0.40.12:8787 nicht erreichen, weil VPN-Split oder Routing fehlt. Richten Sie Quell-IPs der Probes an echte Nutzerpfade aus oder tunneln Sie über denselben Bastion. Exportieren Sie beim Start gateway_bind_interface als Metrik, damit Grafana Drift zwischen Umgebungen zeigt.
Loadbalancer-Health auf Layer-4 kann ebenfalls grün sein, während Layer-7-Auth scheitert—kombinieren Sie Socket-Checks mit einem minimalen authentifizierten HTTP-Call.
Entscheidungsmatrix
| Szenario | Bind bevorzugt | Achtungspunkt |
|---|---|---|
| Einzelner Laptop-Lab | 127.0.0.1 | Vor Remote-Demos umschalten |
| Geteilter Mac mini hinter Corp-Firewall | LAN-IP + Allowlist | DHCP-Reservierungen abstimmen |
| Öffentliche Kante mit Reverse-Proxy | Loopback + nginx vorn | Gateway nicht direkt öffentlich binden |
TIME_WAIT und schnelle Reloads
Skripte, die alle 30 Sekunden neu starten, lassen alte Verbindungen bis zu etwa 60 Sekunden in TIME_WAIT oder erschöpfen Ephemeral-Ports. Legen Sie 5 Sekunden Pause zwischen bootout und bootstrap oder erhöhen Sie den Admin-Port temporär um eins.
Application-Firewall-Fallen
macOS fragt pro neuem Node-Pfad nach eingehenden Verbindungen. Bei „Ablehnen“ bindet lokal erfolgreich, remote läuft in SYN-Timeouts—täuschelich wie Portkonflikt. Standardisieren Sie Pfade oder Signaturen, damit Upgrades keine Dialoglawine auslösen.
Mehrere Gateways auf einem Mac
Blue/Green braucht getrennte Ports wie 8787/8788 und eindeutige Labels. Reservieren Sie Bänder: 8700–8799 für OpenClaw, 8800–8899 für Mocks—ohne Tabelle wählen Freelancer willkürlich.
Staging und Produktion auf einem physischen Host erfordern getrennte Nutzer oder Logpfade, sonst wird lsof unlesbar.
launchctl kickstart und hängende Listener
Nach Freigabe des Ports launchctl kickstart -k gui/$UID/com.example.openclaw nutzen, damit launchd hartnäckige Kinder per SIGKILL beendet. Ohne -k kann ein Middleware-Thread den FD halten, obwohl „shutdown complete“ geloggt wurde. Vorher und nachher einen Ausschnitt von launchctl print sichern, um running → not running zu belegen.
Ephemere Client-Ports und Outbound-Stürme
Tool-Fan-out öffnet tausende ausgehende Verbindungen; macOS kann Ephemeral-Bereiche erschöpfen, während eingehend LISTEN ok wirkt. Clientseitiges EADDRINUSE darf nicht mit Listener-Konflikten verwechselt werden. Beobachten Sie sysctl net.inet.ip.portrange.hifirst bei CI-Runnern auf demselben Host.
Strukturierte Logs bei Bind-Fehlern
JSON mit event="bind_failed", errno, Host, Port, argv-Hash. Postmortems sollen ohne SSH rekonstruierbar sein. errno 48 (EADDRINUSE) zusammen mit dem lsof-Kommando in derselben Zeile erleichtert Onboarding.
Warum Linux-CI macOS-Bind-Races verpasst
Container starten anders als GUI-launchd-Sessions. Nutzen Sie Linux-CI als Compile-Check, führen Sie aber Smoke-Binds auf Apple-Hardware aus, bevor Plists mergen. Ein Tages-Mac-mini-Mietpreis (~16,9 USD) deckt sich mit etwa einer Ingenieursstunde und schließt die Lücke.
FAQ
Gibt macOS Ports sofort frei?
Nach Hochlast-Neustarts kurz warten oder anderen Admin-Port wählen.
Warum Health grün, Nutzer rot?
Interfaces und Pfade der Probes weichen ab.
Ist 0.0.0.0 sicherer als Loopback?
Nein—breitere Fläche, Firewall ergänzen.
Wann Mac mini mieten?
Wenn macOS-Socket- und launchd-Verhalten produktionsnah sein muss.
Portkriege sind langweilig aber teuer. Ein gemieteter Mac mini mit Apple Silicon bei MacHTML—rund 16,9 USD pro Tag—liefert dieselbe launchd-Lebenszyklus- und Socketsemantik wie Produktion, ohne Hardware zu versenden. Für eine Release-Woche hochfahren, lsof-Evidenz sammeln, danach abschalten.
Geringe thermische Lautstärke hilft bei langen SSH-Sessions mit wiederholten Bind-Tests.
OpenClaw-Bind-Probleme auf echtem macOS reproduzieren
Mieten Sie einen Cloud-Mac-mini, um Ports, LaunchAgent-Plists und Health-Probes mit macOS-treuem Socketverhalten zu validieren.