2026年 OpenClaw 在远程物理 Mac 上的环境变量与 SecretRef 实战：openclaw env、LaunchAgent 与 SSH 前台运行差异，以及 Keychain/明文 plist 风险的可复现 Runbook（排查步骤 + FAQ）

1. 三大痛点：为什么「我本地明明好了」在机房 Mac 上失效

1. 环境继承链不同。SSH 登录会话会执行 shell profile，可能悄悄改了 PATH 与 nvm/fnm；LaunchAgent 由 launchd 直接 exec，默认只有 plist 里显式声明的 EnvironmentVariables，极易漏掉「你以为全局生效」的 export。
2. SecretRef 解析依赖文件位置与权限。若 Ref 指向 ~/.openclaw/secrets/...，而作业的工作目录或 HOME 与交互用户不一致，相对路径会静默指向错误位置，表现为偶发 401 或启动阶段直接退出。
3. Keychain 与明文 plist 的合规张力。把 API Token 写进 plist 的 EnvironmentVariables 最快，但备份、配置管理工具与磁盘取证都会碰到明文；纯 Keychain 又可能因无人登录未解锁而失败。需要可审计的折中策略，而不是「先跑起来再说」。

2. 决策矩阵：LaunchAgent 与 SSH 前台运行

下表用于快速判断「该改 plist 还是改 shell 配置」。用户域 Agent 以登录用户身份运行，但与完整 GUI Session 仍可能有 Keychain 差异。

3. 决策矩阵：SecretRef 形态与风险

4. 使用 openclaw env 建立基线

CLI 子命令 openclaw env（若你的发行版使用同名指令）用于在当前进程上下文打印解析后的环境：包括合并后的 PATH、OpenClaw 识别的配置路径、以及 SecretRef 是否已解析为具体值或仅显示指纹/占位（取决于日志级别与安全模式）。

建议在两种场景各执行一次并 diff：① SSH 登录后、与生产相同的 shell；② 用 launchctl asuser 或最小包装脚本模拟 LaunchAgent 环境。下面为示意输出（字段名随版本可能微调）：

$ openclaw env --json
{
  "configPath": "/Users/deploy/.openclaw/openclaw.json",
  "node": { "execPath": "/opt/homebrew/bin/node", "version": "v22.14.0" },
  "env": {
    "PATH": "/opt/homebrew/bin:/usr/bin:/bin",
    "HOME": "/Users/deploy",
    "OPENCLAW_PROFILE": "prod-gateway"
  },
  "secrets": {
    "anthropic": { "ref": "keychain:service:openclaw-anthropic", "resolved": true },
    "webhookHmac": { "ref": "file:~/.openclaw/secrets/webhook.hmac", "resolved": true }
  }
}

若 resolved: false 或 node 路径指向系统旧版，而你在交互 shell 里已经 fnm use 22，几乎可以断定是 LaunchAgent 未注入 PATH——在 plist 增加 PATH 与 NODE_BINARY，或改为用绝对路径的包装脚本启动网关。

5. 七步可复现 Runbook（排查步骤）

1. 固定身份：确认 LaunchAgent plist 位于 ~/Library/LaunchAgents 且 UserName（若使用）与手动调试用户一致。
2. 采集 SSH 基线：登录后执行 openclaw env --json > /tmp/env.ssh.json。
3. 采集 launchd 基线：在无人值守窗口重启 Agent 或 launchctl kickstart 后，从同机另一会话读取网关进程环境（或让包装脚本把 openclaw env 重定向到日志）。
4. Diff 关键字段：PATH、HOME、LANG、TMPDIR、与 OpenClaw 相关的 OPENCLAW_*；SecretRef 是否解析失败。
5. 修正 plist：补齐 EnvironmentVariables，或用 /bin/zsh -lc '/opt/homebrew/bin/openclaw gateway' 强制经过登录 shell（注意引号与性能）。
6. Keychain 分诊：对失败的 SecretRef 执行 security find-generic-password -s "service" -a "account" -w 验证可读性；不可读则调整 ACL 或改文件型 SecretRef。
7. 回归：openclaw doctor、打一条最小 Webhook 或本地回环探测，确认无「首轮成功、重启后失败」。

5.1 LaunchAgent 片段示例（仅演示结构）

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
 "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.openclaw.gateway</string>
  <key>ProgramArguments</key>
  <array>
    <string>/opt/homebrew/bin/openclaw</string>
    <string>gateway</string>
  </array>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
    <key>HOME</key>
    <string>/Users/deploy</string>
  </dict>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

将敏感令牌写入上表 最后手段；更稳妥是保持 plist 干净，仅引用 SecretRef 与文件权限受控的密钥路径。

6. 可引用阈值与清单

• 文件权限：含密钥的 plist 或 secret 文件建议 chmod 600，目录 chmod 700；组共享目录需单独设计 POSIX ACL，避免「同组只读」误配。
• Node 主版本：与 OpenClaw 发行说明一致（示例采用 Node 22 LTS）；LaunchAgent 场景务必用 which node 对齐到 Homebrew 绝对路径。
• 排查时效：一次完整「SSH vs launchd」diff 应在 15 分钟内可重复执行，避免依赖个人笔记本里的未文档化 export。

7. FAQ

8. 在 Mac mini 上固化这套治理

环境变量与 SecretRef 的拉扯，本质上是长期无人值守进程与人机交互会话之间的差异。Apple Silicon Mac mini 在典型网关负载下仍能保持极低待机功耗（常见约 4W 量级）、静音与数月不重启的稳定性，非常适合作为机房里「Always-on」的 OpenClaw 物理节点；macOS 原生支持 launchd、Keychain 与 Unix 权限模型，使你能把 plist、Secret 文件与审计脚本落在同一套系统语义里，而不必在 Linux 容器里模拟钥匙串行为。

若你希望把本文的 Runbook 跑在最省心、最低噪音的硬件上，Mac mini M4 凭借统一内存架构与系统级安全机制（Gatekeeper、SIP、FileVault 可选）仍是 2026 年小团队与跨国研发托管场景的高性价比起点。现在即可通过 ZoneMac 获取节点，把网关与密钥治理一次性落到可审计的基线上。