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 定價指南對照短周期租賃與採購現金流。