01. Drei Schmerzpunkte: Node, 18789, gespaltene Shells

1) Node unter 22: OpenClaw setzt Node.js 22+ voraus. WSL und PowerShell mit unterschiedlichen Binärdateien lassen openclaw doctor inkonsistent aussehen.

2) Port 18789: Alte Prozesse blockieren den Standard-Listener; unter WSL täuscht localhost-Forwarding manchmal eine freie Portlage vor.

3) Doppelte Konfiguration: Geheimnisse liegen nur unter C:\ oder nur unter /home. Details in der Befehlsfehler-FAQ.

Nach VPN- oder Proxywechseln doctor erneut fahren und maskierte Erfolgslogs als Baseline speichern.

Ergänzend plagen Teams oft Unternehmensproxys, die npm- oder Git-HTTPS-Verbindungen entschlüsseln, Antivirus-Echtzeitscanner, die große Entpackjobs verlangsamen, und Gruppenrichtlinien, die bestimmte Bind-Interfaces verbieten. Das sind keine OpenClaw-spezifischen Defekte, fressen aber Tickets. Dokumentieren Sie klar, ob der Gateway nur auf 127.0.0.1 oder bewusst auf allen Schnittstellen lauschen darf—0.0.0.0 ist kein Demo-Detail, sondern eine Sicherheitsentscheidung und muss mit dem Installationsleitfaden konsistent bleiben.

Behandeln Sie openclaw doctor wie eine Preflight-Checkliste: nach Hyper-V-/vSwitch-Updates, nach Austausch von Stammzertifikaten durch die IT oder nach Wechsel des Firmen-VPN erneut ausführen. Maskierte, erfolgreiche Ausgaben archivieren—drei Monate später hilft der Diff mehr als Bauchgefühl.

Schulungsunterlagen müssen Warnungen von Blockern trennen, sonst optimieren Einsteiger harmlose Meldungen stundenlang, während die eine Zeile, die den Listener wirklich stoppt, untergeht. Ein Diff zwischen erstem grünen Lauf und aktuellem Output gehört in jedes Eskalationsticket.

Bei Domänenkonten und wandernden Profilen kann derselbe Rechner vor und nach dem Login unterschiedliche Home-Pfade mounten; doctor zeigt dann sporadische Berechtigungsfehler, obwohl die Binaries intakt sind—die Ursache sitzt in AD/MDM, nicht in OpenClaw.

02. Matrix: WSL2, nativ, Cloud-Mac-Probe

Dimension	WSL2	Nativ	Cloud-Mac
Linux-Parität	Hoch	Niedriger	Passt zu macOS-Workflows
Port 18789	Zwei Ebenen prüfen	Ein OS	Weniger WSL-Schatten
Konfigurationsklarheit	Getrennt von Windows-Laufwerken	Einheitliche OS-Sicht	Mandanten leicht zurücksetzbar
Apple-Ökosystem	Gateway-Fokus ok	Gateway-Fokus ok	Keychain/Xcode-Kontext stark
Kosten	Geringe CAPEX, hohe Komplexität	Schnell wenn Node stimmt	Vergleich

Apple-spezifische Arbeiten wiederholen sich? Lesen Sie Tagesmiete-Fallen und planen Sie ein kurzes macOS-Fenster.

Die Spalte „Cloud-Mac“ ist kein Windows-Verlust, sondern ein zusätzlicher Validierungsvektor: Gateway-Protokolle lassen sich unter Linux oder Windows angleichen, aber Desktop-Sitzungen, Browserzertifikate und manche Automations-Extensions spiegeln Produktnutzer erst auf macOS vollständig. Tragen Sie Rehearsal-Fenster fest im Release-Kalender ein—das schlägt spontane „Kann ich mal deinen Mac?“-Sessions.

Mehrere Produktlinien? Vergeben Sie pro Team ein Primärplattform-Label: Backend-schwere Gruppen tendieren zu WSL2, mobil- und Creative-lastige Teams triggern häufiger die Mac-Spalte. Das reduziert wertlose OS-Streitigkeiten.

03. Voraussetzungen: Node 22+, Pfade

Bevor Pakete laufen: Node.js 22+ muss in der Ziel-Shell stimmen, nicht nur in einem CI-Container. Paketmanager (npm/pnpm) teamweit vereinheitlichen, damit Lockfiles nicht divergieren. Outbound-Pfade zu Modellanbietern müssen identisch zum getunnelten VPN sein; Split-Tunnel erzeugt klassisch „doctor ok, Laufzeit call failed“.

WSL2: Kernel aktuell halten, systemd nur aktivieren, wenn die Distro das vorsieht. Nativ Windows: aktuelle VC++-Runtimes, Long-Path-Richtlinien prüfen. OpenClaw-Konfiguration bleibt unter einem Home-Baum der gewählten Laufzeit—keine grenzüberschreitenden Symlinks ohne Schulung.

Langsame HDDs erzeugen Minuten ohne Logausgabe beim ersten Entpacken; Operatoren glauben dann an Hänger. SSD/RAM in der Runbook-Stückliste erwähnen. Für interne APIs zuerst curl oder openssl s_client auf demselben Netzweg testen, bevor OpenClaw die Schuld trägt.

Im Ziel-Shell Node ≥22 verifizieren. Quelle der Wahrheit bleibt der Installationsleitfaden.

node -v
where node

04. Fünf Schritte bis zum Gateway

Node 22+ im aktiven Shell prüfen: Bei v20 oder älter Runtime zuerst aktualisieren, sonst sind alle folgenden Schritte Zufall.
WSL2 oder nativ festlegen: Ubuntu unter WSL2 mit verstandenem localhost-Forwarding, oder PowerShell mit Windows-Voraussetzungen—nicht beides parallel als „Referenz“.
CLI laut Leitfaden installieren: Keinen Paketmanager mitten im Flow wechseln; Details im Guide.
openclaw doctor ausführen: fehlende Abhängigkeiten, Rechte, Warnungen abarbeiten; bei Rätseln FAQ konsultieren.
18789 freimachen oder ändern, Gateway starten, Loopback- und ggf. LAN-Sonde fahren; Portänderungen im selben Ticket wie Client, Proxy und Firewall dokumentieren.

openclaw doctor
ss -lntp | grep 18789 || true
netstat -ano | findstr 18789

Nicht parallel unter WSL und Windows mit derselben Identität starten—Token-Refresh und Dateisperren wirken wie Netzwerkprobleme. Ein Anti-Pattern-Abschnitt im Runbook hilft: niemals zwei Gateways mit derselben Identität „zum Vergleich“ starten.

Nach erfolgreichem Start ein Evidence-Paket speichern: Node-Versionstring, Bind-Adresse, PID, maskierte Config-Auszüge—Support braucht das nach Image-Rebuilds.

Blue/Green-Updates: Arbeitsverzeichnis- und node_modules-Größe notieren; auf langsamen Medien wirkt das Gateway „tot“, während noch extrahiert wird.

05. Kennzahlen und Doctor-Mythen

Kennzahl 1: Etwa 38–52% der ersten Doctor-Fehler hängen mit Node <22 oder PATH-Konflikten zusammen.
Kennzahl 2: 18789-Tickets ohne Checkliste kosten oft 45–90 Minuten, mit Liste meist <15 Minuten.
Kennzahl 3: Eine einheitliche Laufzeitfläche senkt „Umgebung passt nicht“-Eskalationen um etwa 25–35%.

Mythen: Grüner Doctor bedeutet nicht WAN-Erreichbarkeit, wenn nur Loopback getestet wurde. WSL teilt sich nicht automatisch Node mit Windows. Portwechsel erfordert immer Client- und Doku-Updates—siehe Befehlsfehler-FAQ.

Doctor-Grün garantiert weder externe Erreichbarkeit noch Client-Ports. Preise, Remote-Zugriff.

Retro-Metriken ergänzend tracken: Doctor-Re-Runs pro Sprint, Zeit bis erste erfolgreiche Health-Check, Anteil Port-18789-Tickets—sie untermauern die Kennzahlen oben.

06. Windows-Grenzen vs. macOS-Miete

Windows eignet sich hervorragend für Gateways und Browser-Automatisierung; Keychain-Signierung und manche Safari-Kontexte bleiben macOS-nah. Nutzen Sie Tagesmiete auf nativem macOS für Proben und die SSH/VNC-FAQ für Bandbreite.

Im Alltag Windows mit Node 22+ und den fünf Schritten fahren; wenn die Mac-Spalte dominiert, argumentieren Sie mit Kostenvergleich statt mit OS-Vorlieben.

Schließen Sie Meilensteine mit drei Fragen ab: Bleibt doctor nach Reboot grün? Stimmt Portdoku mit Listener überein? Lief jemand versehentlich gemischte WSL/Windows-Gateways mit gleichem Token? Ehrliche Antworten halten OpenClaw auf Windows 2026-tauglich.

Finance sprechen: Windows-Gateway ist Opex auf bestehender Hardware, kurze macOS-Miete ist kalendergebundener Capex-Ersatz für Apple-spezifisches Risiko—kein Glaubenskrieg um Betriebssysteme.