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 取得節點，把閘道與金鑰治理一次性落到可稽核的基線上。