2026-05-11 OpenClaw 工作區根路徑、倉庫白名單與單體倉庫護欄——無頭租用 Apple Silicon 雲端 Mac（香港 / 東京 / 首爾 / 新加坡 / 美國）
無頭閘道在工具走出您本想編輯的儲存庫之前，幾乎都是「隱形」的。在香港、東京、首爾、新加坡與美國租用的 Mac mini M4 主機上，同一 UID 往往同時承載 OpenClaw、xcodebuild 車道與長期存在的簽章素材——因此「工作區」是一項安全屬性，而不是氛圍感。這份 2026-05-11 手冊把 檔案傳輸路徑策略、launchd 環境變數與金鑰衛生、工作階段 checkpoint 紀律 與 並行車道隔離 串聯成明確的白名單根路徑、解析後的符號連結，以及當助手伸向 ~/Library 或相鄰 CI 目錄時必須失敗閉合的演練。
為何工作區護欄決定共享租用主機上的爆炸半徑
錯誤劃定根路徑，會把看似無害的檔案讀取變成「鑰匙圈鄰域」驚嚇：模型跟隨相對路徑、shell 在 launchd 下對 ~ 的展開與互動式工作階段不一致，或陳舊符號連結從「已授權」子樹指向另一租戶的檢出目錄。生產閘道因此發布檔案系統的正向清單——絕不能只依賴「模型的常識」。將這些清單與自動化工單綁定：每次合併基礎設施設定時，同時審查 OpenClaw 策略檔與相鄰 CI 封裝指令碼。
結構：OPENCLAW_STATE_DIR、CI 檢出與 DerivedData 鄰接
將助手的持久狀態視為資料面儲存：既不要與暫時的 /tmp 複製放在一起，也不要與 Xcode DerivedData 這類會被清理工作中途刪掉的樹相鄰。文件化三個環——狀態環（checkpoint 與策略檔）、工作區環（您授權的 git 根）、草稿環（可丟棄的匯出）——並確保清理 cron 尊重環邊界。當 CI 與助手共享 UID 時，遵循並行車道文章中的隔離指引，避免競態導致鎖檔懸空。
- 狀態環 —— 白名單的版本化片段 + 適用時的密封 JSON。
- 工作區環 —— 每個儲存庫/業務線一個或多個絕對根路徑。
- 草稿環 —— 位於依作業前綴劃分的 TMP 下的帶 TTL 目錄。
與檔案傳輸及 shell 工具策略聯動的白名單
2026-05-07 的檔案傳輸外掛預設偏向拒絕；工作區根應鏡像這些預設，使 fetch/列目錄無法沿符號連結跳到僅因符號連結跳躍才存在的父目錄。依環境（staging 與 prod）編碼根路徑，並二者都保留在 Git 中——維運透過 PR 晉升，而不是臨時 SSH 改檔案。團隊在單體倉庫中嵌入多個微服務時，依套件劃分命名空間根，防止偽裝成「隨便看看」的跨服務讀取。
readlink -f 掃描；APFS firmlink 與企業 VPN 掛載可能在不改磁碟上設定文字的情況下改道路徑。
單體倉庫邊界：SwiftPM 巢狀、Xcode workspace 與 git 子模組
大型單體倉庫對助手暴露多個 Package.swift 清單與混合 Xcode 專案。若團隊對所有權邊界有分歧，應分別釘死根路徑——例如 /build/mobile/ios 與 /platform/android——除非存在第二條白名單項，否則禁止橫向跳躍。子模組目錄僅在通過安全審核時繼承父級授權；否則將巢狀的 .git 目錄視為需更窄範圍的顯式根。
# 核准新根之前解析符號連結
/usr/bin/python3 - <<'PY'
import os
roots = ["/var/ci/job123/acme"]
for r in roots:
print(os.path.realpath(r))
PY
CI 與互動式助手並存時的檢出位置
暫時 CI 常把儲存庫複製到 /var/tmp 下帶雜湊的目錄，或自訂工作磁區；經 SSH 啟動的助手可能預設使用 ~/workspace。統一約定：依區域匯出 ASSISTANT_WORKSPACE_ROOT，並教導編排器只把檢出掛載在已授權前綴之下。當 GitHub Actions 自架標籤與 OpenClaw 路由到同一台 Mac 時，強制使用不同路徑，避免 PR 清理與助手相關草稿並發刪除。
launchd：向非互動閘道匯出根路徑
互動式 shell 會載入 profile 片段；守護程序不會。將白名單鏡像到 plist 的 EnvironmentVariables 或帶校驗和的引用 env 檔。在更新後透過受控的 launchctl kickstart 重新載入閘道，並依 健康探測 指引擷取 stdout——同時驗證 HTTP 就緒與針對禁用路徑的檔案系統探測。
決策矩陣：路徑意圖 vs 執行層
| 情境 | 風險 | 首選緩解 |
|---|---|---|
助手讀取儲存庫並跟隨 ../ |
逃逸到相鄰服務的金鑰 | 正向前綴校驗 + 歸一化後拒絕 .. 段 |
| 指向桌面/文件的符號連結 | 無頭與 GUI 情境下 TCC 預期不同 | 解析符號連結目標；對照 macOS 隱私文件交叉檢查 |
| 共享 UID 的 CI 與助手 | 重疊目錄上的刪除競態 | 依編排 ID 劃分獨立的 TMPDIR 命名空間 |
| 緊急熱修分支 | 臨時放寬白名單卻無回復計畫 | 帶時限的白名單工單 + 自動到期 |
工作區治理的八步上線
- 透過稽核日誌清點過去 30 天內助手接觸過的每個檔案系統路徑。
- 編碼最小白名單；擴大範圍需 VPEng + 安全審核。
- 將策略合併入 Git；將校驗和附加到自動化發佈包。
- 依區域部署 plist/env 更新並配合健康 curl。
- 執行指令碼化拒絕測試，涵蓋符號連結逃逸。
- 培訓值班人員快速回復白名單 PR。
- 讓清理指令碼與草稿 TTL 合約對齊。
- 每季發佈回顧指標，比較拒絕與允許操作的比例。
工作區治理的 SLO 訊號
| 訊號 | 閾值 | 動作 |
|---|---|---|
| 未核准路徑嘗試 | 每閘道每週 > 3 次 | 凍結設定變更；回放事故追蹤 |
| 白名單相對 Git 漂移 | 任意未發佈的手改 | 回復主機；強制僅 PR 工作流程 |
| 符號連結稽核失敗 | 關鍵發現 > 0 | 阻擋發佈；重建解析根對應 |
常見問題
| 問題 | 實務答覆（2026-05-11） |
|---|---|
根路徑是否應整段包含 /Users/ci？ |
否——依流水線或租戶切片；整段根會抵消白名單意義。 |
| 助手能否在工作區外寫入快取？ | 僅能在宣告的草稿前綴內，並附配額與自動汰換。 |
為何 Mac mini M4 租用有利於檔案系統治理
高速 NVMe 與可預期的統一記憶體讓您在 symlink 稽核、三儲存庫並行複製與閘道健康檢查同時執行時不必把交換推到極限——這在事故迭代白名單時很重要。透過 定價頁 依區域規劃容量；在擴大根路徑之前，先把把握不準的同事導向 SSH/VNC 指南。
