2026: OpenClaw-MCP-Umgebungsvariablen – warum launchd-Gateways auf ProxyMac-Mac-mini API-Keys verlieren, die Ihre SSH-Sitzung noch sieht

Ergänzen Sie diesen Deep Dive mit der SSH-Erststart-Checkliste (2026-05-13), sobald Speicher- und PATH-Baselines stimmen. Teams, die OpenClaw auf gemieteten Mac-mini-M4-Hosts in Hongkong, Japan, Korea, Singapur und den USA betreiben, sehen oft, wie MCP-Toolserver mit Fehlern wie „fehlender API-Key“ ausfallen – obwohl dieselbe Binärdatei in einer interaktiven SSH-Sitzung einwandfrei läuft. Die Diskrepanz ist fast nie „OpenClaw hat Krypto vergessen“; es sind zwei verschiedene Prozessbäume mit zwei verschiedenen Umgebungsblöcken. Dieses Playbook erklärt (1), wie launchd LaunchAgents Variablen bereinigt, (2) warum Non-Login-Shells Ihre hübschen .zshrc-Exports überspringen, (3) eine dreischichtige Vergleichstabelle für Terminal, SSH und launchd, (4) gehärtete Plist-Muster plus optionale Wrapper-Skripte, (5) ein Neun-Schritte-Audit, das Rätselraten stoppt, und (6), wie Sie sich an Secrets-Richtlinien halten, ohne Tokens in Logs zu echoen. Querverweise: PATH & Homebrew, Keychain-Secrets, JSONL-Diagnostik und Dev/Staging/Prod-Isolation für die gesamte Toolchain-Geschichte.

Unterschiedliche Prozessbäume, unterschiedliche Umgebungs-DNA

Wenn Sie per SSH auf einen mini gehen und openclaw manuell starten, läuft die Shell typischerweise als Login- oder interaktive Sitzung, lädt ~/.zprofile oder ~/.zshrc und erbt alle export FOO=bar-Zeilen. Ein beim Boot gestarteter LaunchAgent erbt nur das, was launchd injiziert – oft ein gekürztes PATH ohne /opt/homebrew/bin und kein Wissen um Tokens, die Sie letzten Dienstag angehängt haben. Von Gateway geforkte MCP-Unterprozesse kopieren diese magere Umgebung; modellaufgerufene Tools sehen Variablen nicht, die nur im Terminal-Emulator existieren.

• Gemessene Lücke: in Support-Eskalationen lösen sich rund 35 % der Meldungen „in SSH ok, im Daemon kaputt“ allein durch Verschieben der Exports in EnvironmentVariables oder einen Wrapper.
• Timeout-Verwechslung: fehlende Keys äußern sich manchmal als 30–45 s hängende Tools, während SDKs DNS oder Auth-Endpunkte wiederholen – leicht als Netzverlust auf HK → US-Pfaden fehlinterpretiert.
• Parallelität: wenn mehrere Agenten pro Parallelitätsleitfaden laufen, ist race-freies Laden der Umgebung noch wichtiger.

Drei-Wege-Matrix: GUI-Terminal vs. SSH vs. launchd

Quelle	Typisches PATH	Liest .zshrc?	Sieht Keychain-Helfer?	Empfohlen für MCP-Produktion
Terminal.app-Login-Shell	Volles Homebrew	Ja	Oft über Benutzersitzung	Nein – Drift-Risiko
ssh user@host command	Abhängig vom Shell-Modus	Manchmal	Variabel	Nur zum Debuggen
LaunchAgent	Plist-definiert	Nein	Nur wenn programmiert	Ja – explizite Umgebung

Plist-Muster: EnvironmentVariables, ProgramArguments und kleine Wrapper

Apple dokumentiert EnvironmentVariables-Wörterbücher in LaunchAgent-Plists – nutzen Sie sie für nicht-geheime Flags wie NODE_ENV=production oder PYTHONNOUSERSITE=1. Für Secrets entweder eine Datei, die nur der Dienstbenutzer lesen darf (chmod 600), oder einen Wrapper, der Credentials per security find-generic-password holt, bevor Node per exec startet. Wrapper unter /usr/local/libexec oder in einem dedizierten ~svc/bin-Verzeichnis mit unveränderlichem Besitz ablegen.

Diesen Abschnitt mit Gateway-Neustart-Recovery koppeln, damit jede Plist-Änderung durch ein getestetes launchctl kickstart -k-Verfahren läuft.

Neun Audit-Schritte bei „MCP sieht meine Keys nicht“

1. Unter launchd reproduzieren: manuelle SSH-Läufe stoppen; das fehlernde Tool nur über das echte Gateway auslösen.
2. launchd-Umgebung ausgeben: launchctl print gui/$(id -u)/com.example.openclaw (Domain anpassen) und den Block EnvironmentVariables lesen.
3. PATH vergleichen: wenn Homebrew-Binärdateien fehlen, mit absoluten Pfaden oder PATH-Schlüsseln beheben – siehe PATH-Artikel.
4. Shell-Modi testen: ssh host 'env' gegen ssh -t host zsh -lic env laufen lassen, um Login- vs. Non-Login-Deltas zu sehen.
5. MCP-Konfigurationsdateien prüfen: manche Server lesen API_KEY, andere erwarten OPENAI_API_KEY; Namen an Upstream-Dokumentation angleichen.
6. Stdio-Pufferung prüfen: stille Hänger können Pufferung sein, keine Auth – siehe Stdio-Leitfaden.
7. JSONL scannen: Tool-Fehler mit strukturierten Logs korrelieren; Tokens vor externem Teilen redigieren.
8. ulimits prüfen: große Agenten-Batches können Dateideskriptoren erschöpfen, unabhängig von der Umgebung – siehe ulimit-Artikel.
9. Fix dokumentieren: Plist-Diffs mit Ticket-IDs versionieren; Konfigurations-Versionierung einhalten.

Secrets-Grenze: Keychain, Dateien und Rotation

Keychain-Zugriff aus LaunchAgents braucht die richtigen ACLs; interaktive Terminal-Sitzungen fragen oft visuell nach, während headless-Daemonen hart schließen. Richten Sie sich nach Secrets-Hygiene: getrennte Automatisierungs-Keychains, Rotation alle 90 Tage für regulierte Workloads und sicherstellen, dass Replikas in HK / JP / KR / SG / US dieselbe Policy teilen – keine ad hoc duplizierten .env-Dateien.

Wenn mehrere Mandanten einen mini teilen (in Labs vereinzelt), Umgebungsvariablen pro Isolationsleitfaden namespacen, damit Staging nicht per versehentlicher Vererbung Produktions-Tokens liest.

FAQ

Behebt Dockerisierung von OpenClaw Umgebungsprobleme? Container helfen bei Reproduzierbarkeit brauchen aber explizite -e-Flags oder Secret-Volumes – kein Gratis-Mittagessen.

Kann ich .env in ProgramArguments sourcen? Nur über eine Wrapper-Shell; launchd selbst parst keine Dotenv-Dateien.

Hilft sudo -E? Es erhält die Umgebung des Aufrufers bei UID-Eskalation – für Tests nützlich, dauerhaft riskant für MCP, weil die Angriffsfläche wächst.

Warum ProxyMac-Mac-mini der richtige Ort ist, MCP-Umgebung zu härten

Ein dedizierter Mac mini M4 in HK / JP / KR / SG / US liefert langlebige launchd-Supervisoren, planbare Pfade für Wrapper und Apple-Silicon-Effizienz für Dauer-Gateways – ohne pro Region Hardware zu kaufen. Sobald Umgebungsblöcke zwischen CI, Staging und Produktion übereinstimmen, flattern OpenClaw-Agenten nicht mehr, wenn Operatoren sich von SSH abmelden. Preise für Colocation-Entscheidungen, Hilfecenter für Zugangsmuster und VNC, wenn Sie Keychain-Dialoge interaktiv mitverfolgen müssen.