2026 OpenClaw 官方 Docker 一键部署：`docker-setup.sh`、GHCR 与 Control UI（18789）实操 Runbook

约 13 分钟阅读 · MACCOME

谁会遇到问题：已读过官方 Docker 文档，却在本地构建镜像超时、GHCR 拉取失败、18789 端口被占、卷权限导致 Skills 不可写之间来回横跳，缺少「从克隆到 Control UI」的一条龙顺序。本文结论：用 docker-setup.sh + 可选 OPENCLAW_IMAGE 固定最短路径，并与《Docker 生产 Runbook》《Docker 网络分诊》《数据卷与权限》分工。结构：六类坑 → 对照表 → 六步 Runbook → 失败分诊表 → 三 KPI → 转化收束。

为什么「照文档跑」仍会在 Docker 路径上卡住？

官方 Docker 流程依赖本机 Docker Engine、Compose、磁盘与网络出口的一致性；任何一条与团队内「npm 全局安装」或「另一套 compose 目录」混用，都会把症状伪装成「OpenClaw 坏了」。下面六条是 2025–2026 年社区反馈里最常打断最短闭环的因素。

  1. 未区分「源码构建」与「拉取 GHCR」：在 CI 或弱网环境强行本地 docker build，超时后没有切到 OPENCLAW_IMAGE，误以为镜像坏了。
  2. 旧容器仍占用 18789：上一次试验的 compose 项目未停干净，新的 docker-setup.sh 无法绑定 Control UI 端口。
  3. 卷挂载 UID 不匹配：容器内用户与宿主机 ~/.openclaw 目录权限不一致，Skills 或状态写入失败，却只在 UI 上看到「无响应」。
  4. 把配对问题误判为镜像问题：WebSocket 报错与 token 覆盖应走《Gateway 配对与 Token》，而不是反复 compose pull。
  5. 企业代理只放行 npm registry：拉取 ghcr.io 被拦，需要按网络策略改走内部镜像或白名单主机名，与《安装脚本与 npm 轨》中的代理诊断同源。
  6. 在同一主机混跑生产与试验目录：多个 checkout 共用同名卷或环境变量，导致「偶发读到旧 token」。

表 1：本地构建 vs 使用 OPENCLAW_IMAGE（GHCR 预构建）

在评审单里勾选其一作为主路径，另一路径写进回滚脚注，避免口头混用。

维度默认源码构建路径OPENCLAW_IMAGE 拉取 GHCR
适用场景需要改 Dockerfile、调试构建缓存或内网无 ghcr 出口时希望最短时间上屏、带宽有限或 CI 只缓存镜像不缓存源码时
前置条件本机构建资源充足；磁盘预留多 GB 层缓存能访问 ghcr.io 或内部镜像同步；可固定 tag 而非只写 latest
典型风险构建超时、层缓存膨胀、CPU 争用鉴权/限速、tag 漂移、与本地配置版本不完全对齐
回滚思路切到预构建镜像并保留同一数据卷路径回到上一 tag 的 digest 或改回源码构建；记录 compose 变更单
info

提示：官方仓库与文档会迭代；下文命令以「克隆 openclaw 仓库后根目录存在 docker-setup.sh」为前提，若你分支结构不同，请在变更单里写明 commit 与脚本路径。

六步 Runbook：从克隆到可访问 Control UI（18789）

  1. 自检 Docker：docker version 与 Compose v2；预留至少数 GB 磁盘给镜像层与卷（与《Docker 生产》中的资源表对齐）。
  2. 克隆官方仓库并进入根目录：确保 docker-setup.sh 可执行（必要时 chmod +x）。
  3. （可选）导出预构建镜像：export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest（生产建议 pin 到具体 digest 或稳定 tag，而非仅依赖「moving」标签）。
  4. 执行一键脚本：./docker-setup.sh；观察日志是否完成 pull/build 与 compose up，无立即退出码非零。
  5. 打开 Control UI：浏览器访问 http://127.0.0.1:18789（若文档版本变更端口，以你检出版本为准）；确认页面加载而非连接被拒绝。
  6. 最短验证：在 UI 或 CLI 执行官方建议的健康检查；若需配对，进入《配对与 Token》按症状树操作，而不是先改业务配置。
bash
# 例：优先使用 GHCR 预构建镜像（按组织镜像策略替换 tag）
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

# 脚本完成后，本机应能访问 Control UI（默认示例端口 18789）
# open http://127.0.0.1:18789

表 2：常见失败症状 → 优先检查项（分诊顺序）

从上到下排查；若一层已确认无问题再进入下一层，避免同时改镜像、网络和卷。

症状优先检查常与哪篇并读
构建阶段超时或 OOM改走 OPENCLAW_IMAGE；或限制并行 builder、清理 buildkit 缓存《Docker 生产》资源章节
pull 报 401/403 或 TLS企业代理、ghcr.io 白名单、内部镜像同步；勿与 npm registry 混为一谈《安装脚本与 npm 轨》代理节
address already in use :18789docker ps 找旧容器；停 compose 项目或改端口映射（需与文档一致）《Docker 网络分诊》
容器内 Permission denied 写卷宿主机目录 UID/GID、命名卷 vs bind mount；《数据卷与权限》对照表《数据卷与 Skills》
UI 打开但通道无回复先排除模型与通道层；再看 token 与 WS 错误码《配对与 Token》

三条应写进变更单与面板的「硬核」口径

  1. 镜像标识：记录 镜像仓库 + tag + digest（若可获取），而不仅是「用了 latest」；回滚时按 digest 对齐。
  2. Control UI 可达性：把「HTTP 200 / 页面标题 / 健康检查通过」写成布尔门槛，与「容器进程在」分离，避免误判。
  3. 卷路径合同：明确宿主机 ~/.openclaw（或团队约定路径）与 compose 中挂载是否一一对应；升级前后做目录大小与权限快照。

上述口径与官方发行说明一致时，应以官方为准；本文提供工程落地时的检查表位。

为什么「个人笔记本上试一下 Docker」难直接变成生产 Gateway

笔记本环境常有睡眠、磁盘碎片与多版本 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。通用说明见 帮助中心。