2026 OpenClaw MCP 環境變數：為何 ProxyMac Mac mini 上的 launchd 閘道會遺失 API 金鑰，而您的 SSH 工作階段仍看得到
磁碟與 PATH 基線就緒後，請將本深度文與 SSH 首連自檢清單（2026-05-13） 搭配閱讀。團隊在香港、日本、韓國、新加坡與美國的租用Mac mini M4主機上交付OpenClaw時，常見MCP工具伺服器以「遺失 API 金鑰」錯誤失敗——即便同一二進位在互動式SSH工作階段中運作完美。不一致幾乎從不是「OpenClaw 忘記加密」；而是兩棵不同的行程樹繼承了兩組不同的環境區塊。本實務指南說明（1） launchd LaunchAgent 如何淨化變數、（2）為何非登入 shell 會跳過您精美的 .zshrc export、（3）對照終端機、SSH 與 launchd 的三層比較表、（4）強化的 plist 樣式與選用包裝器指令稿、（5）終止猜測的九步稽核，以及（6）如何對齊機密指引而不把權杖 echo 進日誌。請交叉連結PATH 與 Homebrew、金鑰鏈機密、JSONL 診斷與開發／測試／正式隔離以拼出完整工具鏈敘事。
不同行程樹，不同環境 DNA
當您 SSH 進 mini 並手動執行 openclaw 時，shell 通常以登入或互動工作階段執行，會載入 ~/.zprofile 或 ~/.zshrc，並繼承您維護的 export FOO=bar 行。開機啟動的 LaunchAgent 僅繼承 launchd 注入的內容——常是裁切過的 PATH（沒有 /opt/homebrew/bin），以及對您上週二才附加的權杖一無所知。從閘道 fork 出的 MCP 子行程複製那個精簡環境，因此模型呼叫的工具看不到只存在於終端模擬器裡的變數。
- 量測落差：在支援升級中，約35%的「SSH 正常、守行程失敗」通報，純粹靠把 export 移入
EnvironmentVariables或包裝器即可解決。 - 逾時混淆：遺失金鑰有時表現為30–45 秒工具卡住，因 SDK 重試 DNS 或驗證端點——容易被誤判為香港→美國路徑的網路遺失。
- 並行轉折：依並行指南每部主機跑多個代理時，無競態的環境載入更加關鍵。
三方對照：GUI 終端機 vs SSH vs launchd
| 來源 | 典型 PATH | 會讀 .zshrc？ | 看得到金鑰鏈輔助程式？ | MCP 正式環境建議 |
|---|---|---|---|---|
| Terminal.app 登入 shell | 完整 Homebrew | 是 | 常透過使用者工作階段 | 否——漂移風險 |
ssh user@host command | 視 shell 模式而定 | 有時 | 不一定 | 僅供偵錯 |
| LaunchAgent | 由 plist 定義 | 否 | 僅在程式實作時 | 是——明確環境 |
Plist 樣式：EnvironmentVariables、ProgramArguments 與小型包裝器
Apple 文件說明 LaunchAgent plist 內的 EnvironmentVariables 字典——請用它放非機密旗標，例如 NODE_ENV=production 或 PYTHONNOUSERSITE=1。機密則改為僅服務使用者可讀的檔案（chmod 600），或在 exec Node 之前透過 security find-generic-password 拉取憑證的包裝器。請把包裝器放在/usr/local/libexec或專用 ~svc/bin 目錄並鎖定擁有者。
請將本節與閘道重啟復原搭配，讓每次 plist 修改都經過測試過的 launchctl kickstart -k 流程。
「MCP 看不到我的金鑰」九步稽核
- 在 launchd 下重現：停止手動 SSH 執行；僅透過真實閘道觸發失敗工具。
- 倒出 launchd 環境：使用
launchctl print gui/$(id -u)/com.example.openclaw（網域依實際調整）並閱讀 EnvironmentVariables 區段。 - 比對 PATH：若 Homebrew 二進位消失，請以絕對路徑或 PATH 鍵修復——詳見專文PATH 文章。
- 測試 shell 模式：執行
ssh host 'env'對照ssh -t host zsh -lic env以暴露登入與非登入差異。 - 驗證 MCP 設定檔：部分伺服器讀
API_KEY，其他則預期OPENAI_API_KEY；請與上游文件對齊名稱。 - 檢查 stdio 緩衝：靜默卡住可能是緩衝而非驗證——請用stdio 指南確認。
- 掃描 JSONL：將工具失敗與結構化日誌關聯；對外分享前先編修權杖。
- 檢查 ulimits：大批代理可能耗盡檔案描述元，與環境無關——見ulimit 文章。
- 文件化修正：連同工單 ID 提交 plist diff；依設定版本化慣例 rollout。
機密邊界：金鑰鏈、檔案與輪替
LaunchAgent 從 macOS 金鑰鏈讀取需要正確 ACL；互動式終端機常會視覺提示，而無頭守行程則傾向失敗封閉。請對齊機密衛生：分離自動化金鑰鏈、受規管工作負載每90 天輪替金鑰，並確保香港／日本／韓國／新加坡／美國複本共用政策——而非各自複製臨時 .env。
若多部承租方共用單一 mini（實驗室常見但不建議），請依隔離指南為環境變數命名空間化，避免測試誤讀正式權杖。
常見問題
把 OpenClaw 容器化會修好環境問題嗎？ 容器有助再現性，但仍需明確 -e 或祕密掛載——沒有免費午餐。
我能在 ProgramArguments 裡 source .env 嗎？ 僅能透過包裝 shell；launchd 本身不解析 dotenv 檔。
sudo -E 有幫助嗎？ 升權時保留呼叫端環境——測試有用，作為永久 MCP 策略則危險，因為擴大攻擊面。
為何 ProxyMac Mac mini 是硬化 MCP 環境的正確位置
專用Mac mini M4在香港／日本／韓國／新加坡／美國提供長壽 launchd 監督者、包裝器可預測的檔案路徑，以及常駐閘道所需的 Apple Silicon 效率——無需每區採購硬體。一旦 CI、測試與正式的環境區塊一致，營運人員登出 SSH 後 OpenClaw 代理就不會抽風。請在定價頁探索共置選項、倚靠說明中心的存取模式，並在必須互動觀看金鑰鏈提示時透過VNC演練圖形鄰近檢查。
