2026 OpenClaw MCP environment variables: why launchd gateways on ProxyMac Mac mini lose API keys that your SSH session still sees

Pair this deep dive with the SSH first-boot checklist (2026-05-13) once disk and PATH baselines are green, and read HTTP/HTTPS outbound proxy under launchd (2026-05-14) when corporate egress blocks model calls outside your SSH session. Teams shipping OpenClaw on rented Mac mini M4 hosts across Hong Kong, Japan, Korea, Singapore, and the United States routinely watch MCP tool servers fail with “missing API key” errors—even after the same binary works flawlessly inside an interactive SSH session. The mismatch is almost never “OpenClaw forgot crypto”; it is two different process trees inheriting two different environment blocks. This playbook explains (1) how launchd LaunchAgents sanitize variables, (2) why non-login shells skip your pretty .zshrc exports, (3) a three-layer comparison table contrasting Terminal, SSH, and launchd, (4) hardened plist patterns plus optional wrapper scripts, (5) a nine-step audit that stops guesswork, and (6) how to align with secrets guidance without echoing tokens into logs. Cross-link PATH & Homebrew, Keychain secrets, JSONL diagnostics, and dev/staging/prod isolation for a full toolchain story.

Different process trees, different environment DNA

When you SSH into a mini and run openclaw manually, your shell typically executes as a login or interactive session, sourcing ~/.zprofile or ~/.zshrc and inheriting whatever export FOO=bar lines you maintain. A LaunchAgent started at boot inherits only what launchd injects—often a trimmed PATH without /opt/homebrew/bin and zero knowledge of tokens you appended last Tuesday. MCP subprocesses forked from the gateway copy that lean environment, so model-invoked tools cannot see variables that exist solely inside your terminal emulator.

• Measured gap: in support escalations, roughly 35% of “works in SSH, fails in daemon” reports resolve purely by moving exports into EnvironmentVariables or a wrapper.
• Timeout confusion: missing keys sometimes surface as 30–45 s tool hangs while SDKs retry DNS or auth endpoints—easy to misread as network loss on HK → US paths.
• Concurrency twist: when multiple agents run per parallelism guide, race-free env loading matters even more.

Three-way matrix: GUI Terminal vs SSH vs launchd

Source	Typical PATH	Reads .zshrc?	Sees Keychain helpers?	Recommended for MCP prod
Terminal.app login shell	Full Homebrew	Yes	Often via user session	No—drift risk
ssh user@host command	Depends on shell mode	Sometimes	Varies	Only for debugging
LaunchAgent	Plist-defined	No	Only if coded	Yes—explicit env

Plist patterns: EnvironmentVariables, ProgramArguments, and tiny wrappers

Apple documents EnvironmentVariables dictionaries inside LaunchAgent plists—use them for non-secret flags like NODE_ENV=production or PYTHONNOUSERSITE=1. For secrets, either reference a file readable only by the service user (chmod 600) or call a wrapper that pulls credentials via security find-generic-password before execing Node. Keep wrappers under /usr/local/libexec or a dedicated ~svc/bin directory with immutable ownership.

Pair this section with gateway restart recovery so every plist edit flows through a tested launchctl kickstart -k procedure.

Nine-step audit for “MCP cannot see my keys”

1. Reproduce under launchd: stop manual SSH runs; trigger the failing tool via the real gateway only.
2. Dump launchd env: use launchctl print gui/$(id -u)/com.example.openclaw (domain adjusted) and read the EnvironmentVariables stanza.
3. Compare PATH: if Homebrew binaries vanish, fix with absolute paths or PATH keys—see dedicated PATH article.
4. Test shell modes: run ssh host 'env' versus ssh -t host zsh -lic env to expose login vs non-login deltas.
5. Validate MCP config files: some servers read API_KEY while others expect OPENAI_API_KEY; align names with upstream docs.
6. Inspect stdio buffering: silent hangs may be buffering, not auth—confirm with stdio guide.
7. Scan JSONL: correlate tool failures with structured logs; redact tokens before sharing externally.
8. Check ulimits: large agent batches can exhaust file descriptors unrelated to env—see ulimit article.
9. Document the fix: commit plist diffs with ticket IDs; roll through config versioning practices.

Secrets boundary: Keychain, files, and rotation

macOS Keychain access from LaunchAgents requires the right ACLs; interactive Terminal sessions often prompt visually while headless daemons fail closed. Align with secrets hygiene: separate automation keychains, rotate keys every 90 days for regulated workloads, and ensure HK / JP / KR / SG / US replicas share policy—not duplicated ad hoc .env files.

When multiple tenants share one mini (discouraged but seen in labs), namespace env vars per isolation guide so staging cannot read production tokens through accidental inheritance.

FAQ

Will dockerizing OpenClaw fix env issues? Containers help reproducibility but still need explicit -e flags or secret volumes—no free lunch.

Can I source .env inside ProgramArguments? Only via a wrapper shell; launchd itself does not parse dotenv files.

Does sudo -E help? It preserves the caller’s environment while escalating UID—useful for tests, dangerous as a permanent MCP strategy because it broadens attack surface.

Why ProxyMac Mac mini is the right place to harden MCP env

A dedicated Mac mini M4 in HK / JP / KR / SG / US gives you long-lived launchd supervisors, predictable file paths for wrappers, and Apple Silicon efficiency for always-on gateways—without buying hardware per region. Once environment blocks match between CI, staging, and prod, OpenClaw agents stop flapping when operators log out of SSH. Explore pricing for colocation choices, lean on the help center for access patterns, and rehearse GUI-adjacent checks via VNC when you must watch Keychain prompts interactively.