feat: skip rebuild when already on latest version in openclaw-update

openclaw-update now checks HEAD against the latest tag before stopping
the gateway. If already current, it exits early instead of running the
full stop → build → restart cycle. Adds --force flag to override.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: aaajiao

README.md

@@ -110,7 +110,7 @@ openclaw doctor
 | `openclaw-stop/start` | Stop/start service |
 | `openclaw-shell` | Enter VM terminal |
 | `openclaw-doctor` | Run diagnostics |
-| `openclaw-update` | Update app (`--sandbox` to rebuild images) |
+| `openclaw-update` | Update app (`--sandbox` rebuild images, `--force` force rebuild) |
 | `openclaw-sandbox-rebuild` | Rebuild sandbox Docker images |
 
 Full command reference: [docs/commands.md](docs/commands.md)

docs/README.zh-CN.md

@@ -110,7 +110,7 @@ openclaw doctor
 | `openclaw-stop/start` | 停止/启动服务 |
 | `openclaw-shell` | 进入 VM |
 | `openclaw-doctor` | 运行诊断 |
-| `openclaw-update` | 更新版本 (仅应用，`--sandbox` 重建镜像) |
+| `openclaw-update` | 更新版本 (`--sandbox` 重建镜像，`--force` 强制重建) |
 | `openclaw-sandbox-rebuild` | 重建沙箱镜像 |
 
 完整命令参考见 [commands.md](commands.md)

docs/architecture.md

@@ -189,7 +189,7 @@ Gateway 还支持以下扩展能力：
   ├── openclaw-start         # systemctl start
   ├── openclaw-shell         # 进入 VM
   ├── openclaw-doctor        # 运行诊断
-  ├── openclaw-update        # 更新版本 (仅应用，--sandbox 重建镜像)
+  ├── openclaw-update        # 更新版本 (--sandbox 重建镜像，--force 强制重建)
   └── openclaw-sandbox-rebuild # 重建沙箱镜像
 ```
 

docs/commands.md

@@ -61,25 +61,29 @@ openclaw-whatsapp                      # 扫码登录
 | `openclaw-start` | 启动服务 |
 | `openclaw-shell` | 进入 VM 终端 |
 | `openclaw-doctor` | 运行诊断 (openclaw doctor) |
-| `openclaw-update` | 更新版本 (仅应用，`--sandbox` 重建镜像) |
+| `openclaw-update` | 更新版本 (`--sandbox` 重建镜像，`--force` 强制重建) |
 | `openclaw-sandbox-rebuild` | 重建沙箱 Docker 镜像 |
 
 ### 更新命令详情
 
-`openclaw-update` 默认只更新应用（不重建沙箱镜像）：
-1. 停止 Gateway 服务
-2. 获取最新 release tag 并切换
-3. 安装依赖 (`npm install`)
-4. 编译项目 (`npm run build`)
-5. 构建 Control UI (`pnpm ui:build`)
-6. 重新安装 CLI (`npm install -g .`)
-7. 启动服务
+`openclaw-update` 会先检查是否有新版本。如果已是最新，直接跳过构建流程：
 
-使用 `--sandbox` 标志同时重建沙箱镜像：
 ```bash
-openclaw-update --sandbox
+openclaw-update          # 有新版本才更新，已是最新则跳过
+openclaw-update --force  # 强制重新构建（即使已是最新版本）
+openclaw-update --sandbox  # 同时重建沙箱 Docker 镜像
 ```
 
+有新版本时的更新流程：
+1. 获取最新 release tag
+2. 停止 Gateway 服务
+3. 切换到新版本
+4. 安装依赖 (`pnpm install`)
+5. 编译项目 (`pnpm build`)
+6. 构建 Control UI (`pnpm ui:build`)
+7. 重新安装 CLI (`npm install -g .`)
+8. 启动服务
+
 或单独重建沙箱镜像：
 ```bash
 openclaw-sandbox-rebuild

lang/en.sh

@@ -94,10 +94,12 @@ MSG_CMD_CONFIG_BACKED_UP="Backed up to: %s"
 MSG_CMD_CONFIG_USAGE="Usage: openclaw-config [edit|show|backup]"
 
 # openclaw-update
-MSG_CMD_UPDATE_USAGE="Usage: openclaw-update [--sandbox]"
+MSG_CMD_UPDATE_USAGE="Usage: openclaw-update [--sandbox] [--force]"
 MSG_CMD_UPDATE_DESC="Update OpenClaw to the latest version."
 MSG_CMD_UPDATE_OPTIONS="Options:"
 MSG_CMD_UPDATE_SANDBOX_OPT="  --sandbox    Also rebuild sandbox Docker images"
+MSG_CMD_UPDATE_FORCE_OPT="  --force      Force rebuild even if already on latest version"
+MSG_CMD_UPDATE_ALREADY_CURRENT="✅ Already on the latest version. No update needed.\n💡 Use --force to rebuild anyway."
 MSG_CMD_UPDATE_TIP="Tip: To rebuild sandbox only, use openclaw-sandbox-rebuild"
 MSG_CMD_UPDATE_UPDATING="🔄 Updating OpenClaw..."
 MSG_CMD_UPDATE_STOPPING="  Stopping service..."

lang/zh-CN.sh

@@ -94,10 +94,12 @@ MSG_CMD_CONFIG_BACKED_UP="已备份到: %s"
 MSG_CMD_CONFIG_USAGE="用法: openclaw-config [edit|show|backup]"
 
 # openclaw-update
-MSG_CMD_UPDATE_USAGE="用法: openclaw-update [--sandbox]"
+MSG_CMD_UPDATE_USAGE="用法: openclaw-update [--sandbox] [--force]"
 MSG_CMD_UPDATE_DESC="更新 OpenClaw 应用到最新版本。"
 MSG_CMD_UPDATE_OPTIONS="选项:"
 MSG_CMD_UPDATE_SANDBOX_OPT="  --sandbox    同时重建沙箱 Docker 镜像"
+MSG_CMD_UPDATE_FORCE_OPT="  --force      即使已是最新版本也强制重新构建"
+MSG_CMD_UPDATE_ALREADY_CURRENT="✅ 已是最新版本，无需更新。\n💡 如需强制重建: openclaw-update --force"
 MSG_CMD_UPDATE_TIP="提示: 单独重建沙箱可用 openclaw-sandbox-rebuild"
 MSG_CMD_UPDATE_UPDATING="🔄 正在更新 OpenClaw..."
 MSG_CMD_UPDATE_STOPPING="  停止服务..."

scripts/commands/update.sh

@@ -6,16 +6,19 @@
 source "$(dirname "$0")/_common.sh"
 
 SANDBOX=false
+FORCE=false
 for arg in "$@"; do
     case "$arg" in
         --sandbox) SANDBOX=true ;;
+        --force) FORCE=true ;;
         --help|-h)
             echo "$MSG_CMD_UPDATE_USAGE"
             echo ""
             echo "$MSG_CMD_UPDATE_DESC"
             echo ""
             echo "$MSG_CMD_UPDATE_OPTIONS"
             echo "$MSG_CMD_UPDATE_SANDBOX_OPT"
+            echo "$MSG_CMD_UPDATE_FORCE_OPT"
             echo ""
             echo "$MSG_CMD_UPDATE_TIP"
             exit 0
@@ -46,14 +49,7 @@ fi
 
 echo "$MSG_CMD_UPDATE_UPDATING"
 
-echo "$MSG_CMD_UPDATE_STOPPING"
-orb -m "$OPENCLAW_VM_NAME" bash -lc "openclaw gateway stop"
-GATEWAY_STOPPED=true
-trap 'if [ "$GATEWAY_STOPPED" = true ]; then
-    echo "$MSG_CMD_UPDATE_RECOVER"
-    orb -m "$OPENCLAW_VM_NAME" bash -lc "openclaw gateway start" 2>/dev/null || true
-fi' EXIT
-
+# Fetch tags before stopping gateway to check if update is needed
 echo "$MSG_CMD_UPDATE_PULLING"
 orb -m "$OPENCLAW_VM_NAME" bash -lc "cd ~/openclaw && git fetch --tags --force"
 LATEST_TAG=$(orb -m "$OPENCLAW_VM_NAME" bash -lc "cd ~/openclaw && git tag -l 'v*' | grep -v -e '-beta' -e '-rc' -e '-alpha' | sort -V | tail -1")
@@ -62,6 +58,26 @@ if [ -z "$LATEST_TAG" ]; then
     exit 1
 fi
 echo "  -> $LATEST_TAG"
+
+# Check if already on the latest tag
+CURRENT_HEAD=$(orb -m "$OPENCLAW_VM_NAME" bash -lc "cd ~/openclaw && git rev-parse HEAD 2>/dev/null")
+TAG_COMMIT=$(orb -m "$OPENCLAW_VM_NAME" bash -lc "cd ~/openclaw && git rev-parse '$LATEST_TAG^{commit}' 2>/dev/null")
+if [ "$CURRENT_HEAD" = "$TAG_COMMIT" ] && [ "$FORCE" = false ] && [ "$SANDBOX" = false ]; then
+    echo -e "$MSG_CMD_UPDATE_ALREADY_CURRENT"
+    # Still refresh Mac commands in case openclaw-orbstack repo changed
+    OPENCLAW_LANG="$_OPENCLAW_LANG" OPENCLAW_VM_NAME="$OPENCLAW_VM_NAME" \
+        bash "$OPENCLAW_REPO_DIR/scripts/refresh-mac-commands.sh" 2>/dev/null || true
+    exit 0
+fi
+
+echo "$MSG_CMD_UPDATE_STOPPING"
+orb -m "$OPENCLAW_VM_NAME" bash -lc "openclaw gateway stop"
+GATEWAY_STOPPED=true
+trap 'if [ "$GATEWAY_STOPPED" = true ]; then
+    echo "$MSG_CMD_UPDATE_RECOVER"
+    orb -m "$OPENCLAW_VM_NAME" bash -lc "openclaw gateway start" 2>/dev/null || true
+fi' EXIT
+
 orb -m "$OPENCLAW_VM_NAME" bash -lc "cd ~/openclaw && git checkout -- . 2>/dev/null; git checkout '$LATEST_TAG'"
 
 # Ensure pnpm is available (npm/corepack may vanish after apt upgrade)