2026: OpenClaw PATH, Homebrew-Präfixe und fehlgeschlagene Ausführung von MCP-Servern unter launchd auf einem ProxyMac Mac mini

Teams, die OpenClaw auf gemieteten Mac mini M4 in Hongkong, Japan, Korea, Singapur oder den USA betreiben, posten oft Logs, in denen MCP-Tool-Server env: node: No such file or directory oder uvx: command not found ausgeben – obwohl derselbe Befehl in der Terminal.app funktioniert. Dieser Beitrag ist ein PATH-Vertrag zwischen Login-Shell und launchd: warum brew --prefix auf Apple Silicon anders fällt, wie man eine LaunchAgent-Plist ohne Rätselraten liest, und eine fünfstufige Prüfleiter, abgestimmt mit MCP-Server-Setup, Deployment-Troubleshooting und Install und Deploy. Eine breite Matrix vergleicht Symptome, EnvironmentVariables-XML zum Einfügen nach Review, und CTAs auf Hilfe sowie OpenClaw-Hub – kein generischer Marketingsatz. Wenn Sie mehrere Mandanten pro Host teilen, dokumentieren Sie Hash und PATH pro Tenant, sonst mischen Sie CI-Artefakte mit interaktiven Brew-Upgrades, die nachts keinen Menschen in der Nähe haben, der brew doctor liest, solange Ihre Agenten schon laufen. Halten Sie sudo-freie Schreibpfade in Git fest, bevor Sicherheits-Blueprints Ihre ~/.local-Symlink-Kette brechen.

Terminal vs. launchd: zwei getrennte Universen

Interaktive Shells auf macOS führen /etc/zprofile, ~/.zprofile und ~/.zshrc aus, oft mit eval "$(/opt/homebrew/bin/brew shellenv)" vorangestellt. launchd-Agenten erben eine konservative Umgebung: PATH fällt häufig auf /usr/bin:/bin:/usr/sbin:/sbin, sofern die Plist nicht erweitert. OpenClaw-Gateways, die MCP-Server starten, sehen also ein reduziertes Universum, in dem npx- oder pnpm-Shims fehlen, während which npx in der Terminal /opt/homebrew/bin/npx liefert. Nicht „OpenClaw verlor MCP“ – es ist ENOENT von execve, weil der Kernel den Interpreterpfad nicht auflöst. Headless-Builds, die während der ssh-Session gemessen wurden, aber ohne LaunchAgent-Environment deployt sind, führen genau dazu, dass nachts der nächste Brew-Node ein anderes Minor installiert, während Ihre JSON noch auf den vorigen Symlink zeigt, den niemand mit absolutem Pfad abgesichert hat.

• Spaltung beweisen: printenv PATH in einer Einmal-ssh mini 'launchctl print gui/…'-Session gegen die Login-Shell loggen.
• Äußere MCP-Binärdatei absolut pflegen, während Sie PATH für Helfer stabilisieren.
• Drift in Git mitschreiben, siehe Config-Versionierung, damit Upgrades Homebrew-Roots nicht still drehen.

Apple Silicon vs. Intel: Homebrew-Präfix-Matrix (drei Spalten)

Hardware-Generation	Standard-brew-Präfix	Typisches Symptom, wenn es im PATH fehlt
Apple-Silicon-M4-Mac-mini	/opt/homebrew	node fehlt, während /opt/homebrew/bin/node -v v22.x liefert
Intel-Mac-mini (Legacy)	/usr/local	MCP-JSON zeigt noch /opt/homebrew/bin/uvx vom Notebook kopiert
Gemischte Flotte	beide Präfixe auf der Platte	Agenten wählen falsche Shim-Reihenfolge, wenn /usr/local/bin vor /opt/homebrew/bin steht

Mischen Sie keine Intel-x86- und arm64-Interpreter in derselben Plist, ohne beide in den Healthcheck zu hängen: Rosetta kann den Pfadeindruck täuschen, während Ihre npx-Wrapper noch auf arm64 zeigen, die in der lokalen CI nie gestartet wurden. Sammeln Sie file-Ausgabe für jede in MCP referenzierte Binary und legen sie dem Ticket so bei wie einen Compiler-Log – sonst wundert sich niemand, warum der Mini im Rechenzentrum anders pfeift als Ihr 14-Zoll-Notebook, auf dem alles baute.

Plist-EnvironmentVariables, die Reboots überleben

Fügen Sie ein EnvironmentVariables-Dictionary zum LaunchAgent hinzu, der OpenClaw oder den MCP-Supervisor besitzt. Reihenfolge: Homebrew-Shims vor Systempfaden, danach z. B. ~/.local/bin für uv-Toolchains. Nach Editieren immer launchctl bootout gui/$(id -u)/domain plist und kickstart; launchctl unload allein ist ab macOS 14+ brüchig. Koppeln Sie an Health-Checks aus Monitoring-Leitfaden, damit Regressionen binnen 3 Minuten alarmieren, sobald PATH reißt. Markieren Sie Plist-Änderungen mit Ticket-ID und Rollback-Snapshot, bevor Sicherheit dieselbe Datei fürs nächste Quartal auditieren will und Sie keinen diff finden, der nicht nur Ihre lokalen Tests abdeckt.

Beispiel (vor Produktion validieren)

<key>EnvironmentVariables</key> <dict> <key>PATH</key> <string>/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string> </dict>

Fünf Checks, bevor Sie MCP komplett neu schreiben

1. Hash: shasum -a 256 $(which uvx) in der Terminal, vergleichen mit dem absoluten Pfad im MCP-JSON.
2. launchd-Umgebung auslesen: launchctl print user/$(id -u)/limit plus Agentendomain, prüfen ob PATH wirklich landet.
3. Nicht-Login simulieren: env -i PATH=/usr/bin:/bin /opt/homebrew/bin/npx --version testet npx mit minimalem PATH.
4. JSONL: ENOENT in Rollierlogs, siehe JSONL-Diagnostik.
5. Rollback-Doku: LaunchAgent-Plist snapshotten laut Upgrade-Rollback, bevor PATH-Massenupdates auf HK / JP / KR / SG / US-Flotten gehen, und führen Sie einen canary-Job pro Region, statt während Peak-Zeit alle Gateways in einem Rutsch neuzustarten.

Node, uv, Shim-Layout: warum Version Manager unter launchd auseinanderlaufen

Entwickler schätzen fnm, mise und asdf, weil sie dutzende Node-Versionen pro Repository schalten – doch typischerweise passiert das über PATH-Änderungen in ~/.zshrc, und launchd liest diese Datei nicht. Wenn Ihr MCP-JSON npx @scope/server aufruft, muss npx zuerst per absolutem Pfad auffindbar sein; erst danach folgt z. B. der Cache unter ~/.npm. Vom Laptop übernommene JSON landet auf frischen ProxyMac-minis gern in der Falle, dass in der interaktiven Shell corepack enable pnpm aufs PATH setzt, während der LaunchAgent den Shebang an /usr/bin/env node hängt und so den System-Strohmann (auf manchen Images v18) statt des von der Sperrdatei erwarteten v22 trifft. Statt klarer „Datei fehlt“-Zeilen tauchen dann ERR_PNPM_UNSUPPORTED_ENGINE und ähnliches tief in OpenClaw-Wiederholungen auf.

Bei uv gilt Entsprechendes: uvx liegt nach dem üblichen Curl-Setup oft unter ~/.local/bin oder ~/.cargo/bin – sichtbar im Terminal, aber in der PATH-Liste von launchd oft völlig abwesend. Statt die Plist mit noch mehr PATH-Einträgen zuzumüllen, bietet sich ein kurzes Wrapper-Skript wie /usr/local/bin/mcp-env.sh (Besitzer root:wheel, kein weltweit beschreibbares Ziel) an, das PATH einmal setzt und den eigentlichen MCP-Einstieg executiert. Prüfer bevorzugen eine begutachtete Datei vor zwanzig Plist-Fragmenten. Versionieren Sie das Skript in Git mit derselben Strenge wie die Snippets aus Gateway-restart, launchctl und Wiederanlauf, damit die On-Call-Rufbereitschaft Dienstag- und Donnerstags-Deployments anhand derselben Historie vergleichen kann.

Laufzeit	Typische Installationsstelle	Ohne Gegenmaßnahme: was launchd sieht
Node über Homebrew	/opt/homebrew/bin/node	Nur /usr/bin/env zur Auflösung; fehlt der Brew-Shim → ENOENT
uv-Toolchain	~/.local/bin/uvx	Tilde in Plist-Strings expandiert sich nicht von selbst
Corepack-pnpm	Shim neben node	Stimmt nur, wenn dieses node-Verzeichnis in PATH vor /usr/bin steht

FAQ

Alles in /bin/zsh -lc wrappen? Geht, verbirgt aber Fehler und erschwert Signale. Bevorzugen Sie explizites PATH, außer Login-Funktionen nötig sind.

Macht Rosetta-Brew MCP kaputt? Nur wenn Binaries x86_64 sind, der Agent aber arm64 erwartet – file $(which node) an die OpenClaw-Architektur koppeln.

Wo bleiben stdio-Hänger? PATH behebt Exec; Puffer beheben Pipes – stdio buffer lesen, falls MCP nach Start noch stockt, oder wenn Ihre Wrapper Zeilen puffern, während launchd stdout schneller schließt, als npx reagiert, und Ihre Logs trotzdem leer erscheinen, obwohl die CPU schnarrt.

Warum ProxyMac Mac mini der richtige Ort ist, PATH-Verträge einzufrieren

Ein dedizierter Mac mini M4 liefert pro Mandant stabile Hardware: validiertes /opt/homebrew bleibt auf der NVMe neben Ihrem OpenClaw-Workspace, ohne dass jemand geteilte Jenkins-Binaries brew uninstallt. Native arm64 vermeidet Rosetta-Überraschungen, unified memory hält parallele MCP-Worker von NUMA-Kämpfen fern, fünf Regionen erlauben Compliance-nahe Replicas bei identischen, git-getrackten Plist-Snippets. Ist PATH wieder langweilig, skalieren Sie Concurrency per Parallel-Agenten-Leitfaden, buchen Sie Kapazität über Preise und leiten Sie Menschen auf Hilfe, wo GUI-Dialoge VNC brauchen. Sichern Sie die gleiche PATH-Zeile aller screen-Jobs mit, bevor Ihr SRE-Team morgen einen zweiten Dienst derselben Host-Gruppe in einer anderen Zeitzone fährt, ohne Ihre Doku bemerkt zu haben.