2026 OpenClaw MCP 环境变量：为何 ProxyMac Mac mini 上由 launchd 托管的网关会丢失你在 SSH 会话里仍能看到的 API 密钥

磁盘与 PATH 基线就绪后，请将本篇与 SSH 首连自检清单（2026-05-13） 搭配阅读；若企业出口在 SSH 外仍拦截模型调用，请读 HTTP/HTTPS 出站代理与 launchd（2026-05-14）。团队在香港、日本、韩国、新加坡与美国租用的 Mac mini M4 上交付 OpenClaw 时，经常遇到 MCP 工具服务器报「缺少 API 密钥」——即便同一二进制在交互式 SSH 会话里运行完美。根因几乎从来不是「OpenClaw 忘了加密」，而是两套进程树继承了截然不同的环境块。 本手册说明：（1）launchd LaunchAgent 如何裁剪变量；（2）非登录 shell 为何会跳过你精心维护的 .zshrc 导出；（3）一张三层对比表区分 Terminal、SSH 与 launchd；（4）加固的 plist 范式与可选包装脚本；（5）九步审计终结凭感觉改配置；（6）如何在不把令牌写进日志的前提下对齐密钥治理。请交叉阅读 PATH 与 Homebrew、钥匙串密钥、JSONL 诊断 与 开发、预发与生产隔离，拼出完整工具链叙事。工程上还应把「环境漂移」当作一类持续威胁：每次操作系统小版本升级都可能重置默认 PATH 或触发钥匙串 ACL 提示，因此把审计步骤写进季度演练比事后救火便宜一个数量级。

不同进程树，不同环境基因

当你 SSH 到 mini 手工运行 openclaw，shell 往往以登录或交互会话启动，按顺序 source ~/.zprofile 或 ~/.zshrc，继承你维护的 export FOO=bar。开机自启的 LaunchAgent 只继承 launchd 注入的内容——常见是裁剪过的 PATH，缺少 /opt/homebrew/bin，也完全不知道你上周二追加的令牌。由网关 fork 的 MCP 子进程复制这份瘦身环境，于是模型侧工具无法看见仅存在于终端模拟器里的变量。若你把同一命令放进 cron、launchd 与交互 shell 三种入口重复执行，会发现输出差异巨大；这不是随机性，而是 macOS 有意把守护进程与用户会话隔离以降低横向移动面。

• 量化缺口：在支持升级里，大约 35% 的「SSH 可用、守护进程不可用」报告仅凭把导出迁移到 EnvironmentVariables 或包装脚本即可关闭。
• 超时错觉：缺失密钥有时表现为 30–45 秒的工具挂起，因为 SDK 会重试 DNS 或认证端点——极易误判为香港到美国路径的网络中断。
• 并发转折：按 并行智能体指南 运行多路代理时，无竞争地加载环境更为重要。

三方矩阵：图形终端、SSH 与 launchd

来源	典型 PATH	是否读取 .zshrc	能否访问钥匙串助手	是否推荐用于 MCP 生产
Terminal.app 登录 shell	完整 Homebrew	是	常可通过用户会话	否——漂移风险
ssh user@host command	取决于 shell 模式	有时	视情况而定	仅调试
LaunchAgent	由 plist 定义	否	仅在代码显式实现时	是——显式环境

Plist 范式：EnvironmentVariables、ProgramArguments 与小型包装器

苹果文档允许在 LaunchAgent plist 中使用 EnvironmentVariables 字典——适合存放非敏感开关，例如 NODE_ENV=production 或 PYTHONNOUSERSITE=1。敏感信息应引用仅服务账户可读的文件（chmod 600），或由包装脚本先调用 security find-generic-password 再 exec Node。包装脚本建议放在 /usr/local/libexec 或专用 ~svc/bin 目录，并由不可变属主持有。对需要按租户轮换密钥的团队，可在包装层读取机密管理系统下发的短期凭据文件，而不是把长期令牌写进 plist 明文。

将本节与 网关重启与恢复 一起实践，确保每次 plist 变更都走验证过的 launchctl kickstart -k 流程。

针对「MCP 看不到密钥」的九步审计

1. 在 launchd 路径复现：停止手工 SSH 触发，只通过真实网关复现失败。
2. 导出 launchd 环境：使用 launchctl print gui/$(id -u)/com.example.openclaw（域与标签按实际调整）阅读 EnvironmentVariables 段。
3. 对比 PATH：若 Homebrew 二进制消失，用绝对路径或 PATH 键修复——详见 PATH 专文。
4. 测试 shell 模式：运行 ssh host 'env' 对比 ssh -t host zsh -lic env 暴露登录与非登录差异。
5. 校验 MCP 配置文件：部分服务器读 API_KEY，另一些坚持 OPENAI_API_KEY；名称需与上游文档一致。
6. 检查标准输出缓冲：静默挂起可能是缓冲而非认证——参考 stdio 指南。
7. 扫描 JSONL：将工具失败与 结构化日志 关联；对外分享前先脱敏令牌。
8. 查看 ulimit：大批量智能体可能耗尽文件描述符，与环境无关——见 ulimit 文章。
9. 记录修复：将 plist 差异与工单编号一并入库，遵循 配置版本管理 实践。

密钥边界：钥匙串、文件与轮换

LaunchAgent 访问 macOS 钥匙串需要正确 ACL；图形 Terminal 常常弹出可视化提示，而无头守护进程则默认失败关闭。请遵循 密钥卫生：拆分自动化钥匙串、对受监管负载每 90 天轮换密钥，并确保香港、日本、韩国、新加坡与美国副本共享策略，而不是各自复制一份随意的 .env。若实验环境里多台租户共用一台 mini（不推荐但真实存在），请按 隔离指南 为环境变量加命名空间，避免预发误读生产令牌。

从合规视角看，环境变量与密钥存储的审计轨迹同样重要：谁在何时改了 plist、包装脚本校验和是否匹配 Git 提交，应能在五分钟内还原。

常见问题

把 OpenClaw 容器化能解决环境不一致吗？ 容器提升可重复性，但仍需显式 -e 参数或密钥卷挂载——没有免费午餐。

能在 ProgramArguments 里 source .env 吗？ 只能通过包装 shell；launchd 本身不解析 dotenv 文件。

sudo -E 有用吗？ 它在提升 UID 时保留调用方环境——适合一次性测试，但不适合作为永久 MCP 策略，因为扩大了攻击面。

为何 ProxyMac Mac mini 是加固 MCP 环境的合适载体

位于香港、日本、韩国、新加坡或美国的专用 Mac mini M4 提供长期运行的 launchd 监督器、可预测的包装脚本路径，以及 Apple 芯片在常驻网关场景下的能效——无需在每个区域采购实体机。只要 CI、预发与生产的环境块一致，OpenClaw 智能体就不会在操作员退出 SSH 后集体掉线。浏览 定价 选择共置区域，在 帮助中心 巩固访问模式，并在必须观察钥匙串提示时通过 VNC 进行图形侧验证。