2026 : variables d'environnement OpenClaw MCP — pourquoi les passerelles launchd sur Mac mini ProxyMac perdent des clés API que votre session SSH voit encore

Après un disque et un PATH sains, croisez ce guide avec la checklist SSH avant launchd (2026-05-13). Les équipes qui déploient OpenClaw sur des hôtes Mac mini M4 loués à Hong Kong, au Japon, en Corée, à Singapour et aux États-Unis voient souvent échouer les serveurs d'outils MCP avec des erreurs « clé API manquante » — alors que le même binaire fonctionne sans faille dans une session SSH interactive. L'écart n'est presque jamais « OpenClaw a oublié la crypto » ; il s'agit de deux arbres de processus qui héritent de deux blocs d'environnement différents. Ce playbook explique (1) comment les LaunchAgents launchd épurent les variables, (2) pourquoi les shells non connectés sautent vos jolis export dans .zshrc, (3) un tableau comparatif en trois couches entre Terminal graphique, SSH et launchd, (4) des motifs de plist durcis plus des scripts wrapper optionnels, (5) un audit en neuf étapes qui met fin aux suppositions, et (6) comment s'aligner sur les bonnes pratiques secrets sans recopier des jetons dans les journaux. Enchaînez avec PATH et Homebrew, secrets Trousseau, diagnostics JSONL et isolation dev/staging/prod pour une histoire d'outillage complète.

Arbres de processus différents, ADN d'environnement différent

Quand vous vous connectez en SSH sur un mini et lancez openclaw à la main, votre shell s'exécute en général en session de connexion ou interactive, charge ~/.zprofile ou ~/.zshrc et hérite des lignes export FOO=bar que vous maintenez. Un LaunchAgent démarré au boot n'hérite que de ce que launchd injecte — souvent un PATH réduit sans /opt/homebrew/bin et aucune connaissance des jetons ajoutés mardi dernier. Les sous-processus MCP forkés depuis la passerelle copient cet environnement maigre, si bien que les outils invoqués par le modèle ne voient pas les variables qui n'existent que dans votre émulateur de terminal.

• Écart mesuré : dans les escalades support, environ 35 % des rapports « marche en SSH, échoue en démon » se résolvent uniquement en déplaçant les exports vers EnvironmentVariables ou un wrapper.
• Confusion délais : des clés absentes se manifestent parfois par des blocages d'outil de 30–45 s pendant que les SDK réessayent DNS ou les points d'authentification — facile à lire comme une perte réseau sur les chemins HK → US.
• Effet concurrence : lorsque plusieurs agents tournent par guide de parallélisme, un chargement d'environnement sans course compte encore plus.

Matrice à trois voies : Terminal graphique vs SSH vs launchd

Source	PATH typique	Lit .zshrc ?	Voit les aides Trousseau ?	Recommandé pour MCP prod
Terminal.app shell de connexion	Homebrew complet	Oui	Souvent via session utilisateur	Non — risque de dérive
ssh user@host commande	Dépend du mode shell	Parfois	Variable	Uniquement pour le débogage
LaunchAgent	Défini dans le plist	Non	Seulement si codé	Oui — environnement explicite

Motifs de plist : EnvironmentVariables, ProgramArguments et petits wrappers

Apple documente les dictionnaires EnvironmentVariables dans les plists LaunchAgent — servez-vous-en pour des drapeaux non secrets comme NODE_ENV=production ou PYTHONNOUSERSITE=1. Pour les secrets, référencez un fichier lisible uniquement par l'utilisateur du service (chmod 600) ou appelez un wrapper qui récupère les identifiants via security find-generic-password avant de exec Node. Gardez les wrappers sous /usr/local/libexec ou un répertoire dédié ~svc/bin à propriété immuable.

Associez cette section à redémarrage de passerelle pour que chaque modification de plist passe par une procédure testée launchctl kickstart -k.

Audit en neuf étapes pour « MCP ne voit pas mes clés »

1. Reproduire sous launchd : arrêtez les exécutions SSH manuelles ; déclenchez l'outil défaillant uniquement via la vraie passerelle.
2. Vider l'environnement launchd : utilisez launchctl print gui/$(id -u)/com.example.openclaw (domaine ajusté) et lisez le bloc EnvironmentVariables.
3. Comparer PATH : si les binaires Homebrew disparaissent, corrigez avec des chemins absolus ou des clés PATH — voir l'article PATH.
4. Tester les modes shell : exécutez ssh host 'env' contre ssh -t host zsh -lic env pour exposer les deltas connexion vs non connexion.
5. Valider les fichiers de config MCP : certains serveurs lisent API_KEY tandis que d'autres attendent OPENAI_API_KEY ; alignez les noms sur la doc amont.
6. Inspecter la mise en mémoire tampon stdio : les blocages silencieux peuvent être du buffering, pas de l'auth — confirmez avec le guide stdio.
7. Parcourir le JSONL : corrélez les échecs d'outil avec les journaux structurés ; masquez les jetons avant partage externe.
8. Vérifier les ulimits : de gros lots d'agents peuvent épuiser les descripteurs de fichiers sans lien avec l'env — voir l'article ulimit.
9. Documenter le correctif : validez les diffs de plist avec des identifiants de ticket ; déployez selon les pratiques de versionnement de configuration.

Frontière des secrets : Trousseau, fichiers et rotation

L'accès au Trousseau macOS depuis les LaunchAgents exige les bons ACL ; les sessions Terminal interactives invitent souvent visuellement tandis que les démons headless échouent fermés. Alignez-vous sur l'hygiène des secrets : trousseaux d'automatisation séparés, rotation des clés tous les 90 jours pour les charges réglementées, et politique partagée entre répliques HK / JP / KR / SG / US — pas des fichiers .env dupliqués au fil de l'eau.

Lorsque plusieurs locataires partagent un mini (déconseillé mais observé en labo), préfixez les variables d'environnement par guide d'isolation pour que la préproduction ne lise pas les jetons de production par héritage accidentel.

FAQ

Dockeriser OpenClaw règle-t-il les problèmes d'env ? Les conteneurs aident la reproductibilité mais exigent encore des drapeaux -e explicites ou des volumes de secrets — pas de repas gratuit.

Puis-je sourcer .env dans ProgramArguments ? Uniquement via un shell wrapper ; launchd n'analyse pas les fichiers dotenv.

sudo -E aide-t-il ? Il conserve l'environnement de l'appelant en élevant l'UID — utile pour des tests, dangereux comme stratégie MCP permanente car cela élargit la surface d'attaque.

Pourquoi le Mac mini ProxyMac est le bon endroit pour durcir l'env MCP

Un Mac mini M4 dédié à HK / JP / KR / SG / US vous donne des superviseurs launchd longue durée, des chemins de fichiers prévisibles pour les wrappers et l'efficacité Apple Silicon pour des passerelles toujours actives — sans acheter du matériel par région. Une fois les blocs d'environnement alignés entre CI, préproduction et production, les agents OpenClaw cessent de claquer quand les opérateurs ferment SSH. Parcourez les tarifs pour les choix de colocalisation, appuyez-vous sur le centre d'aide pour les modèles d'accès, et répétez les vérifications proches du graphique via le VNC lorsque vous devez observer des invites Trousseau en interactif.