资料核对日期:2026-11-16。未做本地安装实测。本文适用于使用 Docker Desktop 或 Docker Engine、Docker Compose v2 部署 OpenClaw 的环境,目标是让配置、工作区及认证恢复密钥在容器替换后仍可保留。
准备宿主机目录
本篇选择官方预构建镜像,不在本机执行镜像源码构建;因此不把源码构建的内存门槛当作本路线的条件。仍应为容器运行、镜像下载与日志预留宿主机资源。开始前需取得 OpenClaw 官方源码并进入仓库根目录,具体获取方式以官方安装文档为准。
从同一提交的 docker-compose.yml 可核对:OPENCLAW_CONFIG_DIR 绑定到容器内 /home/node/.openclaw,OPENCLAW_WORKSPACE_DIR 绑定到 /home/node/.openclaw/workspace。这两个目录是本次配置和工作区持久化验收的对象;备份范围还应覆盖当前 Compose 实际使用的其他绑定目录,不能只备份容器内部的临时文件。请在当前 Shell 中把它们设为本机持久化目录;具体宿主机路径待确认时,不要继续部署。SQLite 状态应放在 Docker 主机的本地文件系统,不要选择 NFS、SMB 或 CIFS 网络目录。
镜像默认以 uid 1000 的 node 用户运行。如果自定义绑定目录出现权限问题,可在替换示例路径后执行:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
不要把 /path/to/... 原样当作实际路径。
运行官方 Compose 安装流程
选择官方 GHCR 预构建镜像,并从仓库根目录执行:
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
latest 是会移动的稳定发布标签,不是固定版本。需要可重复部署时,应在发布前从官方容器仓库核对并改用明确版本标签;不要把主分支或 main 当作固定稳定版本。
安装脚本会进行环境文件同步、权限处理、引导配置和 Compose 启动。按提示提供真实的服务商凭据;示例占位符不能作为实际密钥。脚本会生成 Gateway token 并写入项目 .env。该文件以及配置目录中的 SQLite 可能包含敏感凭据,备份时应按密钥材料保护。再次运行安装脚本前,先备份现有 .env,核对当前 Shell 中的目录、镜像和端口等变量,再按官方网络与存储说明操作,避免改动现有部署时丢失原配置。
验收目录持久化
先检查服务状态:
docker compose ps
预期结果是 openclaw-gateway 正常运行。然后获取控制台地址:
docker compose run --rm openclaw-cli dashboard --no-open
默认可打开 http://127.0.0.1:18789/,并使用 .env 中生成的 token 完成连接。若配置了自定义宿主机端口,应只替换打印地址中的 18789。
完成一次引导配置后,可通过删除并重新创建容器验证绑定目录,而不是只验证同一容器重启:
docker compose down
docker compose up -d openclaw-gateway
每次操作必须使用同一组 Compose 文件及相同顺序。重新进入控制台后,原配置和工作区仍可用,即说明挂载状态随容器替换保留。宿主机上的绑定目录应继续保留配置和工作区内容。涉及认证信息的备份按敏感资料保护;具体文件范围以当前 Compose 的卷配置和官方存储说明为准。
失败检查:挂载目录权限不足
如果 Gateway 无法启动或日志出现 /home/node/.openclaw 的 EACCES,先查看日志:
docker compose logs -f openclaw-gateway
确认报错指向绑定目录后,检查宿主机目录是否归 uid 1000 所有,并使用前述 chown 命令修正自定义配置目录和工作区。修正后执行:
docker compose restart openclaw-gateway
若仍失败,应复核三个目录变量是否指向本地可写文件系统,以及后续命令是否遗漏了现有的 Compose override 或 extra 文件。不要通过无依据的全目录 chmod 或改为 root 运行来绕过所有权问题。
官方参考资料
- 同一提交的 Docker Compose:逐项核对卷绑定
- docker.md(核对快照)
- compose-operations.md(核对快照)
- networking-and-storage.md(核对快照)
- sandbox-and-troubleshooting.md(核对快照)