Betreiber, die OpenClaw auf headless NodeMac Mac mini M4-Hosts installieren, sehen oft eine funktionierende CLI, während der Gateway-LaunchAgent nach einem Homebrew-Node-Upgrade beendet wird. Diese Matrix vom 2026-05-21 ordnet Installationsfehler-Symptome Ursachen zu, vergleicht gebündelte versus Homebrew-Node-Runtimes, listet acht reproduzierbare Ausrichtungsschritte und enthält FAQ-Antworten für Incident-Tickets.
Upstream-Installer können Node.js unter ~/.openclaw/tools/node/bin/node ablegen, während Ihre SSH-Sitzung zuerst /opt/homebrew/bin/node auflöst. Der von launchd mit Label ai.openclaw.gateway gestartete Gateway-Daemon erbt wieder einen anderen PATH. Wenn diese drei Binaries auseinanderlaufen, laden native Add-ons in der CLI, scheitern aber unter dem Daemon—genau die Bug-Klasse, die 2026 gegen Gateway-Installation gemeldet wird, wenn gebündeltes Node auf sauberen macOS-Hosts ignoriert wird.
Installationsfehler, die wie „OpenClaw kaputt“ wirken, aber PATH-Drift sind
- CLI gesund, Gateway down:
openclaw doctorbesteht per SSH, aberlaunchctl print gui/$(id -u)/ai.openclaw.gatewayzeigt Exit-Code 78 nachbrew upgrade node. - Dreifache Versionsabweichung:
node -vliefert v24.x per SSH, die Plist zeigt auf v22.19, gebündelte Tools melden ein anderes Patch-Level. - npm EACCES bei Installation:
npm i -g openclawscheitert mit Berechtigungsfehlern, weil das globale Prefix für den Service-User nicht beschreibbar ist. - git fehlt auf sauberem macOS: npm install bricht ab, weil git für Abhängigkeiten nötig ist—üblich auf frischen NodeMac-Images, bevor Basispakete installiert sind.
Starten Sie mit der Checkliste für headless Onboarding und Daemon-Abnahme, wenn es die Erstinstallation ist. Für Region und SSH/VNC-Platzierung siehe den Leitfaden Regionen und SSH/VNC vom 2026-05-19. Tiefe Diagnostik: OpenClaw doctor und Health-Diagnostik. Kontoeinrichtung: Hilfebereich und Preise.
Symptom → Ursache → Fix-Matrix (für Runbooks kopieren)
Nutzen Sie diese Tabelle bei Live-Incidents auf gemieteten Mac mini M4-Knoten. Jede Zeile endet mit einem Befehl, den Sie per SSH ohne VNC ausführen können.
| Symptom | Wahrscheinliche Ursache | Erster Fix (SSH) | Verifizieren |
|---|---|---|---|
| npm EACCES | Globales Prefix nicht beschreibbar | npm config set prefix ~/.npm-global |
which openclaw |
| Gateway Exit 78 | Plist-Node ≠ CLI-Node | In ~/Library/LaunchAgents/ai.openclaw.gateway.plist den node-Pfad in ProgramArguments anpassen |
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway |
| doctor warnt bei Node | Unter 22.19 | Node 22 per Installer installieren oder gebündelten Pfad pinnen | node -v ≥ 22.19 |
| npm install failed | git fehlt | xcode-select --install oder brew install git |
git --version |
| Health-Timeout | Socket up, Plugins crashen | ~/.openclaw/logs/gateway.log tailen |
Health-Call 3000 ms OK |
Runtime-Quellenvergleich: Welches Node soll das Gateway besitzen?
Wählen Sie eine primäre Runtime pro Host und dokumentieren Sie sie im Flottenregister. Quellen mischen ohne explizite Plist-Pfade ist 2026 der dominante Fehlermodus auf headless Mac mini M4-Leases.
| Runtime-Quelle | Typischer Pfad | Vorteile auf NodeMac | Nachteile |
|---|---|---|---|
| Bundled (install-cli) | ~/.openclaw/tools/node/bin/node |
Entspricht Upstream-Testmatrix; übersteht brew-Churn | Leicht zu ignorieren, wenn Plist noch auf Homebrew zeigt |
| Homebrew node@22 | /opt/homebrew/opt/node@22/bin/node |
Bekannt für macOS-Admins; schnelle Security-Patches | brew upgrade kann Gateway desynchronisieren |
| User npm-global | ~/.npm-global/bin/openclaw |
Behebt EACCES ohne sudo | launchd muss PATH-Exports explizit erben |
Acht-Schritte-Ausrichtung (reproduzierbar per SSH)
- Drei Node-Pfade erfassen:
which node; node -v; plutil -extract ProgramArguments xml1 -o - ~/Library/LaunchAgents/ai.openclaw.gateway.plist 2>/dev/null | headausführen und ins Ticket einfügen. - Zuerst doctor:
openclaw doctorausführen (Fix-Flags erst nach Lesen des Reports). - Node ≥ 22.19 pinnen: Node installieren oder wählen, das das Upstream-Minimum erfüllt; versehentliche Major-Downgrades blockieren.
- npm-Prefix fixen: Bei EACCES
npm config set prefix ~/.npm-globalsetzen und PATH in~/.zprofiledes Service-Users exportieren. - Plist-node-Pfad ausrichten: Ersten ProgramArguments-Eintrag auf das gewählte node-Binary setzen;
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist, dann erneut bootstrap. - Daemon neu onboarden:
openclaw onboard --install-daemonaus derselben Shell-PATH ausführen, die Sie behalten wollen. - Health-Probe: Loopback-Health mit 3000 ms Timeout aufrufen; Ausgabe neben Host-Seriennummer archivieren.
- CMDB-Leitplanke: Gewählte Runtime-Quelle (bundled / brew / npm-global) erfassen und brew-upgrade-Fenster ohne Gateway-Smoke-Test verbieten.
Hinweis zum Geschäftsworkflow: Support-Teams, die Slack-Tickets über OpenClaw auf einem Singapore Mac mini M4 routen, scheitern weiter, wenn Node-Pfade driften—Runtime-Ausrichtung vor Modell-Prompt-Tuning fixen. Stabile Gateway-Uptime zählt mehr als 50 ms Inference zu sparen, sobald Nachrichten hinter einem abgestürzten Daemon in der Warteschlange hängen.
FAQ: OpenClaw Node.js PATH auf Mac mini M4
Bundled Node oder Homebrew bevorzugen?
Bevorzugen Sie gebündeltes Node auf Produktions-Gateways, wenn install-cli und launchd auf demselben Binary bleiben sollen. Homebrew nur, wenn Sie den Plist-Pfad nach jedem brew upgrade explizit pinnen.
Hilft VNC bei npm-Installationsfehlern?
Selten. PATH- und Berechtigungsfixes sind SSH-Aufgaben. VNC nur für macOS-Privacy-Dialoge, die Automatisierungshelfer blockieren—not für npm EACCES.
Welche Zahlen gehören in den Runbook-Anhang?
Node-Semver, npm-Prefix-Pfad, absoluter Plist-node-Pfad, Health-Timeout 3000 ms und letzter erfolgreicher openclaw doctor-Hash dokumentieren, damit der nächste Bereitschaftsdienst nicht erneut über Versionen diskutiert.
OpenClaw-Installationspfade auf NodeMac zu fixen geht schneller, wenn Sie den Mac mini M4 als langfristiges Gateway-Appliance behandeln, nicht als Wegwerf-Laptop. Apple Silicon M4 liefert Unified Memory für Node-lastige Tool-Chains; natives macOS passt zu OpenClaws Plattformannahmen; SSH und VNC erlauben Ausrichtung von Plist und Shell ohne Hardware zu versenden. Leasing in Hongkong, Japan, Korea, Singapur oder den USA platziert Gateways nahe Slack- und LLM-APIs ohne CAPEX, und dediziertes Metall verhindert, dass Nachbarlärm als „zufällige npm-Fehler“ wirkt. Vergleichen Sie monatliche Knotenkosten auf der Preisseite, bevor Sie einen weiteren Tag mit falsch passenden Node-Binaries verbrennen.