用 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 与挂载清单。