OpenClaw 閘道從環境變數讀取模型 API 金鑰、Webhook 簽章金鑰與頻道權杖——可一旦涉及 launchd，macOS 裡的「環境」就不再單一。本 2026 手冊對比鑰匙圈儲存與 dotenv 檔案，說明如何把金鑰接入 LaunchAgent 而不外洩到互動 shell，並給出輪換步驟，讓無頭雲端 Mac mini M4 合規運作，又不必把憑證貼進團隊聊天。
請與 OpenClaw macOS 安裝與部署 搭配閱讀以完成首次引導。排查遠端存取時，可對照 SSH 隧道遠端管理，避免為複製權杖而隨意放寬綁定位址。日常衛生請對齊 維運手冊：日誌、升級與回滾，使金鑰輪換與二進位升級落在同一套變更紀錄裡。
儲存方式對比
| 機制 | 優勢 | 劣勢 |
|---|---|---|
| macOS 鑰匙圈 | 作業系統保護的 ACL；預設非全域可讀 | 無頭首次授權需一次性 GUI 或規範的 security 命令列 |
磁碟上的 .env |
本機迭代最快 | 備份工具常整目錄拷貝使用者主目錄——易成外洩面 |
Plist EnvironmentVariables |
原生 launchd；可在 IaC 中重現 | 靜息仍為明文——plist 權限限制為 600 |
金鑰類型路由表
| 金鑰類型 | 建議儲存 | 輪換節奏 |
|---|---|---|
| 大型語言模型提供商 API 金鑰 | 鑰匙圈或保管庫代理 → 行程啟動時注入環境 | 60～90 天或員工離職時 |
| Webhook HMAC 金鑰 | 每頻道獨立鑰匙圈項 | 90 天；切換期雙金鑰並行 |
| 非敏感開關 | Plist 或可進 Git 的 JSON 設定 | 隨應用版本發布 |
切勿：把生產金鑰貼進 Slack、郵件或錄影。一旦發生，立即輪換——即便訊息「僅私訊」也應假定金鑰已外洩。
八步可重複的金鑰引導
- 建立服務使用者：專用於閘道的非管理員帳戶；主目錄權限
700。 - 帶外產生金鑰：用保管庫介面或雲端主控台；避免 echo 進 shell 歷史。
- 寫入鑰匙圈：一密一項，描述性標籤，存取控制僅允許閘道二進位。
- 包裝啟動命令：小型 shell 透過
security find-generic-password -w從鑰匙圈匯出變數再 exec OpenClaw——紀錄 stderr，不紀錄明文。 - 在 LaunchAgent 引用包裝器：ProgramArguments 指向包裝指令稿；plist 內不放明文金鑰。
- 乾跑驗證：啟動閘道、確認健康端點，若遷移則在提供商側撤銷舊金鑰。
- 文件化輪換：工單範本列出依賴頻道與 ≤ 30 分鐘回滾視窗。
- 季度稽核：在鑰匙圈路徑之外全碟檢索誤放的
sk-或ANTHROPIC字串。
團隊真正落地的數值護欄
選定三個數字寫進內部 README，並在程式碼審查強制執行：磁碟上明文金鑰檔數量上限（生產為 0）、任意長期權杖最大壽命（預設 90 天）、閘道帳戶 sudo 人數上限（具名 2 人）。承包商需要存取時，把 SSH 金鑰限時綁定到維護視窗，而不是永久放寬鑰匙圈 ACL。
- Plist 權限：凡含金鑰路徑的 plist 皆
chmod 600——即便密文實際在鑰匙圈裡。 - 包裝器逾時：鑰匙圈查詢應在 2 秒內完成；更久往往表示無頭機上阻塞 UI 彈窗——可短時 VNC 一次後複測。
- 金鑰最大年齡：超過 180 天未輪換的項，在下一迭代規劃強制開單。
稽核日誌不列印金鑰本體
合規評審問的是「誰碰了金鑰」而非「金鑰是什麼」。設定閘道日誌輸出憑證來源的雜湊指紋（鑰匙圈項 UUID、保管庫路徑或輪換批次 ID），而非字面權杖。OpenClaw 報錯時，對可能回顯上游 API 金鑰的查詢參數做脫敏；不少 HTTP 用戶端會不小心紀錄完整 URL。若在 SOC 類控制下營運，熱儲存至少保留 30 天、冷儲存 1 年。SSH 工作階段錄影僅用於應急帳戶；日常工程存取應依賴已審查的設定變更，而非現場貼上金鑰。
若 dev/stage/prod 各跑獨立閘道，為每環境劃分獨立鑰匙圈分區，切勿在主機間複製 ~/Library/Keychains 目錄——macOS 可能判損壞或在無頭節點 endless 彈窗。應逐項在新環境引導並在內網文件紀錄條目名，便於值班用 security find-generic-password -a service -s LABEL 驗證存在性而不暴露位元組。
租用雲 Mac 上無頭 macOS 的坑
雲端 Mac 鮮有人在桌邊點「永遠允許」。首次鑰匙圈授權請透過 VNC 完成，日常再用 SSH 改設定。若多名工程師共用同一帳戶，ACL 邊界模糊——應依環境拆分閘道而非共享憑證。偵錯時需要人類可讀環境變數，可用登出即刪的 ramdisk 檔案，避免使用部分映像上重啟後仍存在的 /tmp。
NodeMac 在香港、日本、韓國、新加坡與美國出租專用 Mac mini M4，同時提供 SSH 與 VNC——自動化走 SSH，TCC 彈窗走 VNC。把生產金鑰隔離到與預發實驗不同的主機時，可對照 區域定價 評估爆炸半徑成本。在把保管庫驅動的部署自動化到整隊機器前，請先閱讀 說明文件 完成 SSH 金鑰接入。
常見問題
金鑰應與 LaunchAgent plist 放在同一 Git 儲存庫嗎？
Plist 結構與結構化的非敏感鍵可以進版本庫；敏感值永不——由連線保管庫 API 的 CI 部署工作在安裝時注入。
如何避免輪換金鑰時 API 用量被雙重計費？
在提供商主控台並行新增新舊金鑰，部署帶新鑰匙圈項的閘道同時保持舊金鑰有效，觀察 24 小時健康流量後再撤銷舊金鑰。可避免午夜切換因包裝指令稿一處筆誤而半途失敗。
Mac mini M4 是 OpenClaw 處理金鑰的扎實平台：Apple Silicon 適合高效常駐守護行程，原生鑰匙圈與服務身分結合，物理隔離減少虛擬化側通道問卷裡的雜音。NodeMac 在香港、日本、韓國、新加坡與美國提供帶 SSH／VNC 的專用 Mac mini，讓閘道跑在可預期的裸金屬上。按需租用使安全團隊可在每區域複製強化「金鑰參考機」而無需一次性買滿五機櫃 Mac。
建議把閘道行程使用者與日常登入使用者分離，並在變更審查中明確檢查「誰可以讀取 plist、誰可以 sudo 到服務帳戶」。將金鑰項命名規範寫進維運手冊（例如依環境與提供商前綴），可在事故時快速判斷缺的是哪一類憑證，而不用全庫匯出比對。