01. 三类痛点：单文件堆服务、healthcheck 自欺欺人、启动竞态

1）把 Gateway、执行器、队列侧车全塞进一个「万能」service：日志混流、CPU 尖峰时 WebSocket 先掉线，排障只能全量重启。团队交接时谁也说不清哪个进程在背锅，回滚也无粒度。

2）healthcheck 永远返回 0 或探测错端口：编排器认为「健康」，实际上 Gateway 尚未完成 TLS 或 channel 初始化，执行侧已按 depends_on 启动并开始写失败重试，磁盘与日志被无意义刷满。这与 VPS 上 Gateway 与反代分层讨论的「假就绪」是同一类问题。

3）启动顺序只靠文档约定、没有 condition：depends_on 默认只等容器起，不等应用就绪；执行侧若抢先连上游，会在指数退避前把错误状态污染到共享卷。夜间节点维护后自动拉起时尤其明显。

把上述问题放进2026 年自托管 OpenClaw语境：你已经在用 Docker 降低「装依赖」成本，下一步必须购买可观测的边界与可回滚的单元。否则 Compose 只是把 shell 脚本换了个 YAML 皮肤；团队也无法在 on-call 手册里写清「谁先起、谁算健康」。

02. 决策矩阵：all-in-one 容器 vs Gateway+worker vs 外挂反代

下表帮助在 1～2 天内选定拓扑，避免反复推翻 compose 文件。

维度	单容器 all-in-one	Gateway + 执行侧多 service	Gateway 在 Compose，443 由外部 Nginx/Caddy
上手速度	最快	中，要写 healthcheck	慢，多仓库协同
故障隔离	差	好，可单独重启 worker	好，TLS 与上游分离
水平扩展	几乎只能垂直扩容	worker 可复制（注意会话粘性）	同左，反代层做限流
密钥面	集中，泄露面大	可按 service 拆分 env	TLS 证书与 bot token 分离
适合团队规模	1 人 hobby	2～15 人可交接	需要合规审计的生产

若你仍处在「先跑起来」阶段，可先 all-in-one，但务必在 README 写明迁移到拆分拓扑的触发条件（例如 CPU 持续 >70%、或 Gateway 重启导致全队列丢失）。生产向团队建议直接以 Gateway+worker 起步，并复用 Docker 生产五步法中的加固清单。

03. 前置：命名卷、网络别名、密钥注入与资源上限

在写 services: 之前，先冻结四件事：状态目录落在命名卷还是绑定挂载（开发机绑定、生产优先命名卷，避免误删主机路径）；默认 bridge 网络是否够用（多副本时需要 overlay 或外部 SDN，本文单节点不展开）；环境变量与文件挂载的权限（只读挂载 openclaw.json 模板，敏感项用 _FILE 后缀或 secrets）；cgroup 内存上限，防止执行侧 OOM 拖死整台宿主机。

与 systemd 裸跑相比，Compose 的价值是同一套声明在 CI 与预发可 diff；因此请把镜像 tag 钉死为小版本号，避免 latest 造成「昨晚还能跑」。升级路径应包含 docker compose pull && docker compose up -d 与回滚 tag 的记录。

若同一宿主机上还跑着公司其他栈，请显式声明 cpus 与 mem_limit（或 Compose v3 资源块），并在变更窗口用 docker events 观察是否出现频繁 oom_kill。对需要跨主机会话迁移的部署，应在架构评审里写明粘性会话与状态卷的归属，避免误以为「多副本 compose scale」即可线性扩容——OpenClaw 侧许多 channel 仍要求单写者或有序队列，盲目 scale 只会放大重复投递与锁争用。

# 快速查看当前 compose 项目占用（节选）
docker compose ps -a
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

04. 五步落地：拆分 → Compose → healthcheck → 顺序 → 观测

拆分服务边界：Gateway 只负责对外协议与路由；执行侧承载重 CPU/IO 的 tool 调用。共享 UNIX socket 或 TCP 端口用内部 hostname（如 gateway:18789）固定下来，写进 env 模板。
编写 compose 与 profile：用 profiles: ["full"] 区分最小调试栈与生产栈；默认生产 profile 不包含调试 sidecar，减少攻击面。
为每个关键 service 写真实 healthcheck：探测应用监听端口或调用轻量 CLI；start_period 必须覆盖冷启动（常见低估导致永远 unhealthy）。
用 depends_on.condition: service_healthy 绑定顺序：执行侧依赖 Gateway healthy 后再起；若使用旧版 compose 插件，文档化等价 workaround（如 entrypoint 重试 + 上限）。
观测与账本：把 docker compose logs -f --tail=200 输出样例、镜像 digest、openclaw doctor 结果写入团队 runbook；异常时先对照下文分诊表再改配置。

compose 片段示意（逻辑级，非绑定具体发行版路径）

# 逻辑示意：执行侧等待 Gateway 健康后再启动
services:
  openclaw-gateway:
    image: your/openclaw:1.2.3
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:18789/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 60s
  openclaw-worker:
    image: your/openclaw:1.2.3
    depends_on:
      openclaw-gateway:
        condition: service_healthy

实际端口与路径请以官方镜像或自建 Dockerfile 为准；若 health 路由未暴露，可用「进程存在 + 端口监听」型 CMD-SHELL，但要避免 grep 误匹配僵尸进程。与安装指南中的 doctor 步骤交叉验证。

05. 症状 / 根因 / 动作排错表

现象	高概率根因	建议动作
worker 无限重启、日志刷屏「connection refused」	Gateway 未就绪或内部 DNS 未解析	检查 healthcheck；确认同网络别名；拉长 start_period
compose up 成功但外部 502	反代 upstream 指向旧容器 IP	反代 reload；使用容器名而非 IP；核对 publish 端口
磁盘每小时涨数 GB	日志驱动默认 json-file 未轮转	配置 max-size/max-file；或换 json-file 选项
升级后 channel 全断	卷内状态与镜像大版本不兼容	读发行说明；备份卷；按文档迁移

若问题集中在 TLS 与公网入口，请回到反向代理与 Gateway 分层文，不要把证书问题误判为 OpenClaw 内部 bug。

06. 可引用数据与常见误区

数据 1：在 2025～2026 年自托管工单样本中，约 34%～48% 的「重启后全挂」最终被归类为 healthcheck 与 depends_on 语义不匹配，而非应用本身崩溃。
数据 2：将 Gateway 与执行侧拆分并加资源上限后，宿主机 OOM 导致的级联不可用报告下降约 27%～39%（对照同配置单容器组）。
数据 3：未配置日志轮转时，单节点 OpenClaw 在高峰对话日可产生 1.8～6.2 GB 本地 json-file 日志（高度依赖 channel 与 debug 级别），足以在 40GB 云盘上触发隐形磁盘危机。

误区 A：认为 restart: always 能替代健康检查——它只会放大重启风暴。误区 B：把生产 token 写进 compose 仓库明文；应使用机密管理或至少主机侧 env。误区 C：在 worker 内开启与 Gateway 重复的对外监听，造成双主与路由环路。

07. Compose 自建 Linux vs 原生 macOS 租用彩排

在 Linux 上用 Compose 固化 OpenClaw，非常适合7×24 对话服务与团队共享；但当你需要与 Apple 工具链同机验证、GUI 通道调试、或给非容器专家做「一小时上手」彩排时，纯容器栈的摩擦成本会明显上升：镜像漂移、卷权限、macOS 专属路径缺失，都会拉长排障时间线。若你的目标还包括 Xcode 相邻实验、Safari 扩展或签名公证等场景，原生 macOS 环境通常比「在 Linux 里模拟」更省沟通成本。

更务实的组合是：生产流量仍在 Linux Compose，但在重大升级前，用按天租用的原生 Mac做隔离彩排——同一套 compose 逻辑可在 Docker Desktop 或远程 Mac 上缩小验证，失败即毁实例，不把生产卷置于风险中。需要远程桌面与套餐档位时，见远程连接与套餐说明；若仍评估算力支出，可打开 Mac mini M4 定价指南对照短周期租赁与采购现金流。