用 Docker / Compose 跑 OpenClaw Gateway的團隊裡，最耗時的往往不是「鏡像能不能拉下來」，而是重啟、升級或 docker compose down 之後配對與配置像被「一鍵清零」，或 Skills 目錄在容器裡只讀、日誌報 Permission denied，卻與官方 Troubleshooting 裡的網路條目對不上。本文與《Docker 網路分診》《裝後 doctor 排錯》《Docker 生產與 Gateway 常駐》《遠端 Mac 常駐運維》分工：給出六類卷/權限側誤區、兩張「該掛哪裡 vs 反模式」表、症狀→命令→修復矩陣、可複製檢查片段、六步 Runbook、三條面板口徑；排障順序上堅持先卷與 UID/GID，再網路與反代。
容器鏡像本身是只讀模板；會丟的只有寫進可寫層、匿名卷或未持久化路徑裡的狀態。下列信號建議寫進變更單，並與 Compose 文件版本號、鏡像 tag 同一行評審。
down -v 或清理腳本會連帶刪掉配對與緩存，表現為「我明明沒改配置」。:ro，官方示例若需要寫入 token 緩存或本地狀態則會靜默失敗或退回到內存態，重啟後消失。docker commit 看似能救場，但升級鏡像或換 tag 後仍丟；不適合作為生產策略。若你已對照《網路分診》仍遇到「CLI 偶發連上、重啟必掛」，優先回到本篇核對命名卷是否真落在預期盤、進程用戶能否寫 Skills，再決定是否調整 network_mode 或反代。
具體子路徑以你當前鏡像與文檔為準；下表給的是工程上應問的三類問題：是否跨容器生命周期、是否要備份、是否多人只讀。把結論寫進 README 與 on-call 手冊。
| 類別 | 典型應持久化內容 | 推薦做法 | 反模式 |
|---|---|---|---|
| 配置與密鑰材料 | Gateway 地址、provider 選擇、通道 token 路徑等 | 宿主機 bind 或命名卷；權限收緊到運行用戶 | 寫進鏡像層；或放在會被同步軟體「清理」的臨時目錄 |
| 運行態與配對 | 設備配對、會話恢復所需狀態 | 單獨子目錄 bind，升級前 tar 備份 | 依賴匿名卷且未在 Compose 文檔化；prune 一鍵消失 |
| Skills / 擴展 | 團隊維護的 skill 文件、腳本 | bind 到倉庫旁固定路徑；CI 與生產同一路徑約定 | :ro 卻需要運行時生成緩存；或 UID 不可寫 |
| 日誌與緩衝 | 大體積日誌、臨時導出 | 獨立卷或宿主路徑，配合輪轉 | 寫滿容器可寫層觸發 OOM 或意外只讀文件系統 |
執行下列檢查時，保持同一終端會話記錄下鏡像 ID、Compose 項目名與卷名，便於升級回滾；與《生產 Runbook》裡的發布檢查表共用一頁。
| 症狀 | 優先檢查 | 常見修復 | 仍失敗時 |
|---|---|---|---|
docker compose up 後一切「像全新安裝」 | docker inspect 看 Mounts 是否指向預期宿主路徑；是否用了 -v 清理過卷 | 改為顯式 bind 或命名卷；文檔化 down 是否允許帶 -v | 核對是否連錯 Compose 項目目錄 |
| Skills 不生效 / 寫入失敗 | 容器內 id 與宿主 ls -ln 所有者 | 調整 user、chmod 或在 Dockerfile/entrypoint 對齊 UID | 檢查是否 :ro 掛載 |
| Permission denied 刷屏 | SELinux/AppArmor（Linux）或 Docker Desktop 文件共享列表（macOS） | Linux：標籤或 :z 類策略按安全基線評估；macOS：把路徑加入 File Sharing | 回到《網路分診》前確認不是偽裝的磁碟只讀 |
| 升級鏡像後「半可用」 | 配置 schema 是否變更；舊數據目錄是否仍掛載 | 按發行說明做遷移；先備份再升級 | 跑 openclaw doctor 對照官方 Breaking changes |
# 1) 掛載是否落在你以為的宿主路徑（替換容器名）
docker inspect -f '{{ json .Mounts }}' <container> | jq .
# 2) 容器內運行用戶（與宿主目錄所有者對照）
docker exec -it <container> id
# 3) Compose 實際使用的項目卷（避免匿名卷漂移）
docker compose ls
docker volume ls | grep <project>
# 4) 升級前備份 bind 目錄示例（路徑按團隊約定）
tar czf openclaw-state-$(date +%Y%m%d).tgz ./openclaw-data/
提示：在遠端 Mac 上若使用 Docker Desktop，宿主路徑常位於用戶目錄下；若使用 Linux 雲機，同一 Compose 片段可能需要不同的 user 與權限策略——不要把「筆記本上能跑」直接等價於「池化機器上能跑」。
down -v 會刪除什麼」。openclaw doctor 與通道探活，避免假陰性。Permission denied、EACCES；若與 Gateway 版本升級同向飆升，優先懷疑掛載模式而非 provider。上述指標與《遠端 Mac 常駐運維》中的磁碟與日誌口徑並列：卷問題會表現為磁碟暴漲或只讀；不要未看磁碟水位就先擴 CPU。
補充一條可執行觀察：在 2025–2026 周期，許多團隊把 Gateway 與 Skills 放在同一宿主目錄樹下；若未對「僅日誌可增長」的子目錄單獨配額，會出現日誌把整塊 bind 撐滿後，配置寫入也一併失敗的連鎖症狀。此時應先按常駐篇做日誌輪轉或拆卷，而不是反覆重建容器。
另一條常見誤判是把 docker compose restart 與 down/up 混用：前者通常保留同名容器與已聲明卷；後者若帶上清理參數會改變數據命運——值班手冊裡應用同一動詞表，避免口頭說「重啟」實際執行了帶卷刪除的流水線。
筆記本上的單用戶目錄權限與遠端池化機器的多租戶/自動化登錄不同；睡眠、磁碟同步與手改 bind 路徑會讓「昨天能跑」無法複製。要把 OpenClaw 當作 24/7 控制面，需要路徑合同化、鏡像升級可回滾、權限可審計。
在自家機器上反覆試錯適合學習，但生產上更常見成本是值班時間與通道不可用。碎片化的臨時容器缺少穩定掛載與宿主權限模型時，升級與擴容反而增加故障面。對需要長期在線、可備份、可遷移的 Gateway 而言，把宿主環境落在具備 Apple Silicon 物理節點與多地區選擇的 Mac 雲平臺上，通常比反覆在個人設備上改 Docker 更利於形成標準 Runbook。MACCOME 提供多地 Mac Mini M4 / M4 Pro 租賃與公開幫助文檔，適合作為 OpenClaw 與自動化工作流的執行平面；先查幫助與價格，再按區域頁落單。
落地建議：先在目標宿主（與生產同類型：Docker Desktop 或 Linux）跑通表 2 全量檢查，再接入通道與模型；避免「本地 Mac 試通就上雲」導致 UID 與路徑雙重漂移。
若團隊同時使用 Kubernetes，請記住 Pod 重建比 Compose 更頻繁：無狀態容器假設下，任何未入 PVC 的目錄都會在滾動發布中丟失；這與本文強調的「顯式持久化」原則一致，只是檢查入口換成 kubectl describe pvc 與掛載清單。