告别十几个小时的慢速拉取，3分钟完成版本更新
⚠️ 特别说明：Docker 部署无法通过网页界面升级
OpenClaw 的 Web 界面中的 “Update now” 按钮仅适用于 npm/源码安装方式。
如果你是通过 Docker 部署的（无论是直接用 docker run 还是 docker-compose），点击按钮无效是正常现象。这是因为 Docker 容器的更新需要拉取新镜像并重建容器，而 Web 界面触发的命令是针对宿主机环境的。
Docker 部署的正确升级方式：只能通过命令行操作。
问题背景
OpenClaw 的 Docker 镜像托管在 GitHub Container Registry（ghcr.io），国内服务器拉取速度极慢，首次安装可能耗时十几个小时。
配置 Docker Hub 镜像加速（阿里云、中科大等）对 ghcr.io 无效，因为加速器只加速 Docker Hub。
解决方案
使用国内 ghcr.io 镜像站（南京大学镜像）进行拉取，速度可达 10-50 MB/s，几分钟即可完成。
极速升级步骤（命令行操作）
第一步：拉取最新镜像（从国内镜像站）
docker pull ghcr.nju.edu.cn/openclaw/openclaw:latest
速度很快，通常 1-3 分钟完成。
第二步：打标签（让本地配置能识别）
docker tag ghcr.nju.edu.cn/openclaw/openclaw:latest ghcr.io/openclaw/openclaw:latest
这一步将国内镜像站的镜像“重命名”为官方镜像的名称，这样你的 docker-compose.yml 不需要做任何修改。
第三步：重建并重启容器
cd /opt/openclaw
docker compose up -d
Docker Compose 会发现本地已存在最新镜像，直接使用它重建容器，不会再去慢速的官方源拉取。
第四步：验证升级
# 查看容器状态
docker compose ps
# 查看日志确认无报错
docker compose logs --tail=30
刷新浏览器页面，版本号已更新，更新提示消失。
完整升级命令（一键复制）
# 1. 拉取（国内镜像站）
docker pull ghcr.nju.edu.cn/openclaw/openclaw:latest
# 2. 打标签
docker tag ghcr.nju.edu.cn/openclaw/openclaw:latest ghcr.io/openclaw/openclaw:latest
# 3. 重建容器
cd /opt/openclaw && docker compose up -d
# 4. 查看日志
docker compose logs --tail=30
原理说明
| 步骤 | 作用 |
|---|---|
docker pull ghcr.nju.edu.cn/... | 从国内镜像站高速下载（避开 ghcr.io 慢速） |
docker tag ... ghcr.io/... | 重命名镜像，让 docker-compose.yml 能找到 |
docker compose up -d | 重建容器，使用本地已有镜像 |
其他可用的国内 ghcr.io 镜像站
如果南京大学镜像不可用，可以尝试以下备选：
| 镜像站 | 地址 | 说明 |
|---|---|---|
| 上海交大 | ghcr.mirrors.sjtug.sjtu.edu.cn | 教育网友好 |
| 中科院 | ghcr.io.mirrors.ustc.edu.cn | 需确认可用性 |
使用示例：
docker pull ghcr.mirrors.sjtug.sjtu.edu.cn/openclaw/openclaw:latest
docker tag ... # 同上
注意事项
-
镜像同步延迟：国内镜像站通常每 10-30 分钟同步一次官方仓库，
latest标签可能比官方延迟最多 1 小时，不影响日常使用。 -
首次安装也适用：这个方法同样适用于首次安装，不必等十几个小时。
-
配置文件无需修改：全程不需要修改
docker-compose.yml，保持image: ghcr.io/openclaw/openclaw:latest即可。 -
以后每次更新都用这个流程：看到 Web 界面提示 "Update available"，不要点击按钮，按上述三步命令行操作即可。
常见问题
Q：为什么不能点击 Web 界面的 "Update now" 按钮？
A：Docker 部署的 OpenClaw 运行在容器内，Web 界面触发的更新命令（如 npm update、git pull）是针对宿主机文件系统的，容器内无法执行，也无法修改只读的容器文件系统。所以点击按钮会无效或报错。
Q：拉取时提示 unauthorized 或 404？
A：镜像站可能暂时不可用，换一个备选镜像站重试。
Q：docker compose up -d 后还是慢速拉取？
A：说明本地没有正确的标签镜像，检查第二步 docker tag 是否执行成功：
docker images | grep openclaw
应该看到两条记录，一条来自 ghcr.nju.edu.cn，一条来自 ghcr.io，且 IMAGE ID 相同。
Q：如何确认升级成功？
A：浏览器登录 OpenClaw，查看页面右下角或设置中的版本号，更新提示消失即表示成功。
总结
| 安装方式 | 升级方式 | Web 界面按钮是否有效 |
|---|---|---|
| npm/源码安装 | openclaw update | ✅ 有效 |
| Docker 部署 | 命令行：docker pull + docker tag + docker compose up -d | ❌ 无效 |
Docker 部署用户请记住：升级只能通过命令行完成，网页按钮对你无效。
保存这个流程，以后每次更新 3 分钟搞定！ 🚀
