如何安全更新 OpenClaw——版本管理與回滾

軟體更新是一件矛盾的事。你想要最新功能和安全修補，但又怕更新後什麼東西壞掉。對於 OpenClaw 這種「運行中的 AI Agent 框架」來說，更新的風險更高一些——如果更新後 gateway 啟動失敗，你所有的 Telegram bot、API 端點、排程任務都會跟著停擺。

好消息是，OpenClaw 的更新機制設計得相當穩健。它有明確的頻道系統、dry-run 預覽、自動備份和回滾能力。只要你按照正確的流程操作，更新應該是一個無痛的過程。

本文會詳細介紹 OpenClaw 更新的每一個環節，讓你在按下更新按鈕前有足夠的信心。

檢查目前版本

在做任何事之前，先確認你目前的版本：

openclaw --version

輸出範例：

openclaw v2.4.1 (stable)
node v22.12.0
platform linux-x64

注意三個資訊：

OpenClaw 版本：v2.4.1
所在頻道：stable
Node.js 版本：確保更新後仍然相容

你也可以用更詳細的版本查詢：

openclaw version --verbose

這會額外顯示：

安裝路徑
設定檔位置
Gateway 版本（如果正在運行）
已安裝的 skill 版本

更新頻道

OpenClaw 有三個更新頻道，類似 Chrome 的頻道系統：

stable（穩定版）

openclaw config set update.channel stable

每 2-4 週釋出一次
經過完整的測試週期
適合生產環境和不想冒險的使用者
預設頻道

beta（測試版）

openclaw config set update.channel beta

每 1-2 週釋出一次
包含即將進入 stable 的功能
適合想提前體驗新功能、願意偶爾遇到 bug 的使用者
可能有小問題，但不至於影響核心功能

dev（開發版）

openclaw config set update.channel dev

幾乎每天都有更新
包含最新的開發進度
可能不穩定，API 可能有 breaking change
只適合 OpenClaw 的貢獻者或願意幫忙測試的進階使用者

確認目前頻道

openclaw config get update.channel

切換頻道

切換頻道後需要執行一次更新來套用：

openclaw config set update.channel beta
openclaw update

注意：從 dev 切回 stable 時，如果 stable 的最新版本比你目前的 dev 版本舊，OpenClaw 會進行「降級」。降級的風險比升級高，因為可能涉及資料庫 schema 的 backward migration。建議在降級前做好完整備份。

檢查可用更新

在真正更新之前，先看看有什麼新東西：

openclaw update --check

輸出範例：

Current version: v2.4.1 (stable)
Latest version:  v2.5.0 (stable)

Changes in v2.5.0:
  - New: Telegram group multi-agent support
  - New: Custom skill marketplace
  - Fix: Memory leak in long-running gateway sessions
  - Fix: Telegram message parsing for edited messages
  - Breaking: Minimum Node.js version raised to 22.0.0

Changes in v2.4.3:
  - Fix: Race condition in concurrent agent invocations
  - Fix: Docker healthcheck endpoint timeout

Changes in v2.4.2:
  - Fix: WSL2 socket permission issue
  - Improvement: Faster gateway startup time

--check 只顯示資訊，不會做任何修改。

閱讀 Changelog

對於重大更新（minor 或 major 版本），強烈建議閱讀完整的 changelog：

openclaw changelog

或查看線上版本：

openclaw changelog --open

這會在瀏覽器中打開 OpenClaw 的 changelog 頁面。

重點關注的標記：

Breaking：不向下相容的變更，可能需要你修改設定或 Agent 定義
Deprecated：即將被移除的功能，目前仍可使用但建議遷移
Security：安全性修補，應該盡快更新

更新前備份

這是最重要的步驟。雖然 OpenClaw 的更新程序會自動建立備份，但手動備份給你額外的安全網。

需要備份的項目

# OpenClaw 的設定和資料目錄
~/.config/openclaw/
  openclaw.json          # 主設定檔
  agents/                # Agent 定義
  skills/                # 自訂 skill
  memory/                # Agent 記憶
  sessions/              # 對話 session
  credentials/           # API 金鑰和憑證

快速備份

# 建立帶時間戳記的備份
BACKUP_DIR=~/openclaw-backup-$(date +%Y%m%d-%H%M%S)
cp -r ~/.config/openclaw "$BACKUP_DIR"
echo "Backup created at: $BACKUP_DIR"

驗證備份

# 確認備份完整性
diff -rq ~/.config/openclaw "$BACKUP_DIR"
# 沒有輸出表示完全一致

# 確認檔案數量
find "$BACKUP_DIR" -type f | wc -l

備份 systemd service 檔案

如果你有自訂的 systemd service 設定：

cp ~/.config/systemd/user/openclaw.service "$BACKUP_DIR/"
# 或
sudo cp /etc/systemd/system/openclaw.service "$BACKUP_DIR/"

使用 `--dry-run` 預覽

在真正更新之前，你可以用 dry-run 模式看看更新會做什麼：

openclaw update --dry-run

輸出範例：

[dry-run] Would update from v2.4.1 to v2.5.0
[dry-run] Download size: 48MB
[dry-run] Backup will be created at: ~/.config/openclaw/backups/v2.4.1-20260224
[dry-run] Actions:
  1. Stop gateway
  2. Backup current installation
  3. Download v2.5.0
  4. Update binary
  5. Run migration scripts
  6. Restart gateway
[dry-run] Estimated downtime: 15-30 seconds
[dry-run] No actual changes were made.

dry-run 會模擬整個更新流程，包括下載大小估算和預計停機時間，但不會修改任何檔案。

執行更新

確認一切就緒後，執行更新：

openclaw update

如果要更新到特定版本（而不是最新版）：

openclaw update --version v2.5.0

更新過程中你會看到進度輸出：

Checking for updates...
Current: v2.4.1 → Target: v2.5.0

[1/5] Stopping gateway...                    done
[2/5] Creating backup...                     done (saved to ~/.config/openclaw/backups/v2.4.1-20260224)
[3/5] Downloading v2.5.0...                  done (48MB)
[4/5] Installing update...                   done
[5/5] Starting gateway...                    done

Update complete! v2.4.1 → v2.5.0
Gateway is running on port 19080

更新後驗證

# 確認版本
openclaw --version

# 確認 gateway 狀態
openclaw status

# 快速健康檢查
curl -sf http://localhost:19080/health

如果你有 Telegram bot，也建議發一條測試訊息確認 bot 正常回應。

更新時保留的項目

了解哪些東西會在更新中被保留，哪些可能被改變，是緩解更新焦慮的關鍵。

一定會保留的

項目	路徑	說明
主設定檔	`openclaw.json`	更新不會覆蓋你的設定
Agent 定義	`agents/*.md`	你寫的所有 Agent prompt
Agent 記憶	`memory/`	Agent 累積的長期記憶
對話 session	`sessions/`	進行中的對話歷史
API 憑證	`credentials/`	你的 API 金鑰
自訂 skill	`skills/`	你自己寫的 skill

可能被修改的

項目	說明
內建 skill	會被更新到最新版本
資料庫 schema	可能有 migration
預設設定值	新版本可能引入新的預設設定

可能需要你手動調整的

項目	何時需要
`openclaw.json`	新版本引入了新的必要欄位
Agent 定義	新版本改變了 prompt 格式或語法
自訂 skill	API 有 breaking change 時

可能壞掉的東西

即使更新流程正常完成，某些功能可能因為 breaking change 而停止工作。以下是最常見的情況。

Skill 相容性問題

如果你的 Agent 使用了第三方 skill，而新版本改變了 skill API：

# 列出已安裝的 skill 和相容性狀態
openclaw skills list --check-compat

輸出可能類似：

Installed skills:
  web-search     v1.2.0  ✓ compatible
  code-runner    v0.9.1  ✗ requires update (minimum v1.0.0 for OpenClaw v2.5.0)
  lobstalk       v2.0.0  ✓ compatible

修復方式：

# 更新不相容的 skill
openclaw skills update code-runner

Node.js 版本不符

新版 OpenClaw 可能要求更高版本的 Node.js^[1]：

Error: OpenClaw v2.5.0 requires Node.js >= 22.0.0, but found v20.11.0

# 更新 Node.js
nvm install 22
nvm use 22

# 或用系統套件管理員
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

設定檔 schema 變更

如果新版本改變了 openclaw.json 的 schema：

# 驗證設定檔
openclaw config validate

如果有問題，OpenClaw 通常會給出明確的遷移指示：

Warning: 'telegram.botToken' has moved to 'telegram.bots[0].token' in v2.5.0
Run 'openclaw config migrate' to automatically update your config.

openclaw config migrate

Docker 映像檔更新

如果你是用 Docker 運行 OpenClaw，更新流程不同。

單一容器

# 拉取最新映像檔
docker pull openclaw/openclaw-stack:latest

# 停止並移除舊容器
docker stop openclaw
docker rm openclaw

# 用新映像檔啟動
docker run -d \
  --name openclaw \
  -p 19080:19080 \
  -v openclaw-data:/data \
  -e OPENCLAW_GATEWAY_TOKEN=your-token-here \
  openclaw/openclaw-stack:latest

重要：確保你使用了 named volume（openclaw-data:/data）。如果你用的是 bind mount，資料會保留在主機上；如果什麼都沒掛載，容器移除後資料就丟了。

Docker Compose

如果你用 Docker Compose：

# docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw-stack:2.5.0  # 指定版本比 latest 更安全
    ports:
      - "19080:19080"
    volumes:
      - openclaw-data:/data
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your-token-here
    restart: unless-stopped

volumes:
  openclaw-data:

# 更新映像檔並重啟
docker compose pull
docker compose up -d

指定版本 tag

在生產環境中，建議用精確的版本 tag 而不是 latest：

# 查看可用的版本 tag
# 到 Docker Hub 或 GitHub Container Registry 查看
docker pull openclaw/openclaw-stack:2.5.0

這樣你可以精確控制何時更新，而不會在 docker compose pull 時意外拉到不穩定的版本。

回滾程序

如果更新後出了問題，你需要回滾。

自動備份回滾

OpenClaw 的更新程序會自動建立備份。查看可用的備份：

openclaw update --list-backups

Available backups:
  v2.4.1-20260224-143022  (98MB)  2026-02-24 14:30:22
  v2.3.0-20260210-091505  (92MB)  2026-02-10 09:15:05

回滾到上一個版本：

openclaw update --rollback

或回滾到特定備份：

openclaw update --rollback v2.4.1-20260224-143022

回滾會：

停止 gateway
還原二進位檔和設定到備份的狀態
重新啟動 gateway

手動回滾

如果自動回滾失敗（例如 openclaw 指令本身壞了），你可以手動操作：

# 用 npm 安裝指定版本
npm install -g openclaw@2.4.1

# 從手動備份還原設定
cp -r ~/openclaw-backup-20260224-143000/* ~/.config/openclaw/

# 重啟 gateway
openclaw gateway start

Docker 回滾

Docker 的回滾最簡單——直接用舊版本的映像檔：

docker stop openclaw
docker rm openclaw

docker run -d \
  --name openclaw \
  -p 19080:19080 \
  -v openclaw-data:/data \
  -e OPENCLAW_GATEWAY_TOKEN=your-token-here \
  openclaw/openclaw-stack:2.4.1  # 指定舊版本

自動更新設定

OpenClaw 支援自動更新，但預設是關閉的。

啟用自動更新

openclaw config set update.auto true

自動更新的行為

{
  "update": {
    "auto": true,
    "channel": "stable",
    "schedule": "weekly",
    "notifyOnly": false,
    "restartAfterUpdate": true,
    "backupBeforeUpdate": true
  }
}

參數	說明	預設值
`auto`	是否自動更新	`false`
`channel`	更新頻道	`stable`
`schedule`	檢查頻率：`daily`、`weekly`、`monthly`	`weekly`
`notifyOnly`	只通知不自動安裝	`false`
`restartAfterUpdate`	更新後自動重啟 gateway	`true`
`backupBeforeUpdate`	更新前自動備份	`true`

排程更新（搭配 systemd timer）

如果你想在特定時間視窗內自動更新（例如凌晨 3 點），可以用 systemd timer：

cat > ~/.config/systemd/user/openclaw-update.service << 'EOF'
[Unit]
Description=OpenClaw Scheduled Update

[Service]
Type=oneshot
ExecStart=/usr/bin/openclaw update --auto --backup
EOF

cat > ~/.config/systemd/user/openclaw-update.timer << 'EOF'
[Unit]
Description=OpenClaw Weekly Update Timer

[Timer]
OnCalendar=Mon *-*-* 03:00:00
Persistent=true
RandomizedDelaySec=1800

[Install]
WantedBy=timers.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now openclaw-update.timer

RandomizedDelaySec=1800 會在 03:00-03:30 之間隨機選一個時間執行，避免所有使用者同時向更新伺服器發送請求。

更新最佳實踐

生產環境更新檢查清單

檢查 changelog——特別注意 Breaking 和 Security 標記
閱讀社群回饋——等新版本釋出 2-3 天後，看看有沒有人回報嚴重問題
在測試環境先試跑——如果可能的話
備份——手動備份到 OpenClaw 目錄以外的地方
dry-run——預覽更新動作
選擇低峰時段——避免在使用者活躍時更新
更新——執行 openclaw update
驗證——檢查版本、gateway 狀態、Telegram bot
監控——更新後的 30 分鐘內留意日誌

版本釘選策略

在多台機器上部署 OpenClaw 時，建議所有機器使用相同版本。你可以在設定中釘選版本上限：

{
  "update": {
    "maxVersion": "2.5.x"
  }
}

這會允許 patch 版本的自動更新（2.5.0 → 2.5.1），但不會跳到 2.6.0。

託管方案的更新

如果你使用 ClawTank，更新由平台自動管理。ClawTank 會在確認新版本穩定後，以滾動方式更新所有容器。每個容器在更新前會自動備份，如果更新後健康檢查失敗，會自動回滾。

你不需要擔心版本管理、備份策略或回滾程序——這些都是平台自動處理的。但你仍然可以在 ClawTank 控制面板中查看目前版本、changelog 和更新狀態。

總結

OpenClaw 的更新流程可以簡化為五個步驟：

openclaw update --check — 看看有什麼更新
openclaw changelog — 閱讀變更內容
備份 ~/.config/openclaw/
openclaw update --dry-run — 預覽更新動作
openclaw update — 執行更新

如果出問題，openclaw update --rollback 能快速還原。

養成定期更新的習慣。Stable 頻道的更新經過充分測試，大多數情況下是安全的。但無論如何，備份永遠是你的安全網。

如何安全更新 OpenClaw——版本管理與回滾

檢查目前版本

更新頻道

stable（穩定版）

beta（測試版）

dev（開發版）

確認目前頻道

切換頻道

檢查可用更新

閱讀 Changelog

更新前備份

需要備份的項目

快速備份

驗證備份

備份 systemd service 檔案

使用 --dry-run 預覽

執行更新

更新後驗證

更新時保留的項目

一定會保留的

可能被修改的

可能需要你手動調整的

可能壞掉的東西

Skill 相容性問題

Node.js 版本不符

設定檔 schema 變更

Docker 映像檔更新

單一容器

Docker Compose

指定版本 tag

回滾程序

自動備份回滾

手動回滾

Docker 回滾

自動更新設定

啟用自動更新

自動更新的行為

推薦設定

排程更新（搭配 systemd timer）

更新最佳實踐

生產環境更新檢查清單

版本釘選策略

託管方案的更新

總結

References

使用 `--dry-run` 預覽