誰會遇到問題：已讀過官方 Docker 文件，卻在本地構建映像超時、GHCR 拉取失敗、18789 埠被佔、卷權限導致 Skills 不可寫之間來回橫跳，缺少「從克隆到 Control UI」的一條龍順序。本文結論：用 docker-setup.sh + 可選 OPENCLAW_IMAGE 固定最短路徑，並與《Docker 生產 Runbook》《Docker 網路分診》《資料卷與權限》分工。結構：六類坑 → 對照表 → 六步 Runbook → 失敗分診表 → 三 KPI → 轉化收束。
官方 Docker 流程依賴本機 Docker Engine、Compose、磁碟與網路出口的一致性；任何一條與團隊內「npm 全域性安裝」或「另一套 compose 目錄」混用，都會把症狀偽裝成「OpenClaw 壞了」。下面六條是 2025–2026 年社群反饋裡最常打斷最短閉環的因素。
docker build，超時後沒有切到 OPENCLAW_IMAGE，誤以為映像壞了。docker-setup.sh 無法繫結 Control UI 埠。~/.openclaw 目錄權限不一致，Skills 或狀態寫入失敗，卻只在 UI 上看到「無響應」。compose pull。ghcr.io 被攔，需要按網路策略改走內部映像或白名單主機名，與《安裝指令碼與 npm 軌》中的代理診斷同源。OPENCLAW_IMAGE（GHCR 預構建）在評審單裡勾選其一作為主路徑，另一路徑寫進回滾腳註，避免口頭混用。
| 維度 | 預設原始碼構建路徑 | OPENCLAW_IMAGE 拉取 GHCR |
|---|---|---|
| 適用場景 | 需要改 Dockerfile、除錯構建快取或內網無 ghcr 出口時 | 希望最短時間上屏、頻寬有限或 CI 只快取映像不快取原始碼時 |
| 前置條件 | 本機構建資源充足；磁碟預留多 GB 層快取 | 能訪問 ghcr.io 或內部映像同步；可固定 tag 而非只寫 latest |
| 典型風險 | 構建超時、層快取膨脹、CPU 爭用 | 鑑權/限速、tag 漂移、與本地配置版本不完全對齊 |
| 回滾思路 | 切到預構建映像並保留同一資料卷路徑 | 回到上一 tag 的 digest 或改回原始碼構建；記錄 compose 變更單 |
提示：官方倉庫與文件會迭代；下文命令以「克隆 openclaw 倉庫後根目錄存在 docker-setup.sh」為前提，若你分支結構不同，請在變更單裡寫明 commit 與指令碼路徑。
docker version 與 Compose v2；預留至少數 GB 磁碟給映像層與卷（與《Docker 生產》中的資源表對齊）。docker-setup.sh 可執行（必要時 chmod +x）。export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest（生產建議 pin 到具體 digest 或穩定 tag，而非僅依賴「moving」標籤）。./docker-setup.sh；觀察日誌是否完成 pull/build 與 compose up，無立即退出碼非零。http://127.0.0.1:18789（若文件版本變更埠，以你檢出版本為準）；確認頁面載入而非連線被拒絕。# 例：優先使用 GHCR 預構建映像（按組織映像策略替換 tag） export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest" ./docker-setup.sh # 指令碼完成後，本機應能訪問 Control UI（預設示例埠 18789） # open http://127.0.0.1:18789
從上到下排查；若一層已確認無問題再進入下一層，避免同時改映像、網路和卷。
| 症狀 | 優先檢查 | 常與哪篇並讀 |
|---|---|---|
| 構建階段超時或 OOM | 改走 OPENCLAW_IMAGE；或限制並行 builder、清理 buildkit 快取 | 《Docker 生產》資源章節 |
| pull 報 401/403 或 TLS | 企業代理、ghcr.io 白名單、內部映像同步；勿與 npm registry 混為一談 | 《安裝指令碼與 npm 軌》代理節 |
address already in use :18789 | docker ps 找舊容器；停 compose 專案或改埠對映（需與文件一致） | 《Docker 網路分診》 |
| 容器內 Permission denied 寫卷 | 宿主機目錄 UID/GID、命名卷 vs bind mount；《資料卷與權限》對照表 | 《資料卷與 Skills》 |
| UI 開啟但通道無回覆 | 先排除模型與通道層；再看 token 與 WS 錯誤碼 | 《配對與 Token》 |
~/.openclaw（或團隊約定路徑）與 compose 中掛載是否一一對應；升級前後做目錄大小與權限快照。上述口徑與官方發行說明一致時，應以官方為準；本文提供工程落地時的檢查表位。
筆記本環境常有睡眠、磁碟碎片與多版本 Docker Desktop 試驗殘留，和獨佔算力、固定出口、可審計卷與 token 邊界的生產要求相沖突。僅依賴臨時容器而不固化映像 digest、卷合同與健康檢查，會在第一次真實流量時暴露配對與權限問題。
對需要把 Gateway 長期跑在穩定 Apple Silicon 上、並保留清晰資料目錄與監控的團隊，MACCOME 的 Mac 雲主機提供多地區節點與彈性租期，便於與本文 Runbook 的「最短閉環」銜接後再做常駐加固；建議先閱讀公開價格與幫助中心，再與《Docker 生產》《配對與 Token》一起做變更評審。
試點：在獨佔遠端機上跑通六步並記錄映像 digest 與卷快照，再決定是否合併到月租/季租與監控告警。
常見問題
應該先讀本文還是《Docker 生產 Runbook》？
需要「第一次跑通 UI」先按本文六步；要把 Gateway 放進生產變更窗、回滾與監控，再並讀《Docker 生產》。價格見 租賃價格說明。
OPENCLAW_IMAGE 和 npm 全域性安裝的 CLI 會衝突嗎？
衝突點多在埠、環境變數與資料目錄；同一臺機只應有一套「主 Gateway」配置。遷移順序見 安裝指令碼與 npm 軌。
18789 能改成對外訪問嗎？
若需公網或內網統一入口，應疊加反代與 TLS 策略，與《Docker 生產》及既有反代類文章的安全段落一起評審，而不是直接綁 0.0.0.0。通用說明見 幫助中心。