更新

OpenClaw 迭代速度很快（尚未到「1.0」）。將更新視為部署基礎設施：更新 → 檢查 → 重啟（或使用 openclaw update，它會自動重啟）→ 驗證。

推薦：重新執行網站安裝程式（原地升級）

首選的更新方式是重新執行網站的安裝程式。它會偵測現有安裝、原地升級，並在需要時執行 openclaw doctor。

curl -fsSL https://openclaw.ai/install.sh | bash

備註：

如果不想再次執行設定精靈，加上 --no-onboard。

對於原始碼安裝：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

安裝程式僅在儲存庫乾淨時才會執行 git pull --rebase。

對於全域安裝，腳本底層使用 npm install -g openclaw@latest。
舊版備註：clawdbot 仍可作為相容性墊片使用。

更新前

確認安裝方式：全域（npm/pnpm）或從原始碼（git clone）。
確認閘道執行方式：前景終端或受管服務（launchd/systemd）。
備份你的客製化：
- 設定：~/.openclaw/openclaw.json
- 憑證：~/.openclaw/credentials/
- Workspace：~/.openclaw/workspace

更新（全域安裝）

全域安裝（擇一）：

npm i -g openclaw@latest

pnpm add -g openclaw@latest

我們不建議使用 Bun 作為閘道 runtime（WhatsApp/Telegram 有 bug）。

切換更新頻道（git + npm 安裝均適用）：

openclaw update --channel beta
openclaw update --channel dev
openclaw update --channel stable

使用 --tag <dist-tag|version> 進行一次性的特定標籤/版本安裝。

詳情請見開發頻道。

備註：npm 安裝時，閘道啟動時會提示更新（檢查當前頻道標籤）。停用：update.checkOnStart: false。

核心自動更新器（選用）

自動更新器預設關閉，是閘道的核心功能（非外掛）。

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

行為：

stable：發現新版本時，OpenClaw 等待 stableDelayHours，然後套用 stableJitterHours 的確定性 jitter（分散推出）。
beta：按 betaCheckIntervalHours 間隔檢查（預設：每小時），有更新時套用。
dev：不自動套用；手動使用 openclaw update。

使用 openclaw update --dry-run 在啟用自動化前預覽更新動作。

然後：

openclaw doctor
openclaw gateway restart
openclaw health

備註：

如果閘道以服務方式執行，openclaw gateway restart 比殺程序更好。
如果鎖定在特定版本，見下方「回滾 / 鎖定」。

更新（`openclaw update`）

對於原始碼安裝（git checkout），推薦：

openclaw update

它執行安全的更新流程：

要求乾淨的工作目錄。
切換到選定的頻道（標籤或分支）。
對 upstream 執行 fetch + rebase（dev 頻道）。
安裝相依套件、建置、建置 Control UI，並執行 openclaw doctor。
預設重啟閘道（使用 --no-restart 跳過）。

如果透過 npm/pnpm 安裝（無 git metadata），openclaw update 會嘗試透過套件管理工具更新。如果無法偵測安裝方式，改用「更新（全域安裝）」。

更新（Control UI / RPC）

Control UI 有 Update & Restart（RPC：update.run）：

執行與 openclaw update 相同的原始碼更新流程（僅 git checkout）。
寫入重啟 sentinel 及結構化報告（stdout/stderr 尾部）。
重啟閘道並將報告發送到最後活躍的 session。

如果 rebase 失敗，閘道中止操作並在不套用更新的情況下重啟。

更新（從原始碼）

從儲存庫 checkout：

必須執行：`openclaw doctor`

Doctor 是「安全更新」指令。刻意無聊：修復 + 遷移 + 警告。

備註：如果是原始碼安裝（git checkout），openclaw doctor 會提議先執行 openclaw update。

典型動作：

遷移已棄用的設定鍵 / 舊版設定檔位置。
審核 DM 政策並對風險性「open」設定發出警告。
檢查閘道健康狀態，可提議重啟。
偵測並遷移舊版閘道服務（launchd/systemd；舊版 schtasks）到當前 OpenClaw 服務。
在 Linux 上確認 systemd user lingering（讓閘道在登出後繼續運作）。

詳情：Doctor

啟動 / 停止 / 重啟閘道

CLI（任何作業系統皆可）：

openclaw gateway status
openclaw gateway stop
openclaw gateway restart
openclaw gateway --port 18789
openclaw logs --follow

如果使用受管服務：

macOS launchd（app 附帶的 LaunchAgent）：launchctl kickstart -k gui/$UID/ai.openclaw.gateway（使用 ai.openclaw.<profile>；舊版 com.openclaw.* 仍有效）
Linux systemd user service：systemctl --user restart openclaw-gateway[-<profile>].service
Windows（WSL2）：systemctl --user restart openclaw-gateway[-<profile>].service
- launchctl/systemctl 僅在服務已安裝時有效；否則執行 openclaw gateway install。

Runbook 與服務標籤：閘道 runbook

回滾 / 鎖定（出問題時）

鎖定（全域安裝）

安裝已知可正常運作的版本（將 <version> 替換為最後正常的版本）：

npm i -g openclaw@<version>

pnpm add -g openclaw@<version>

小技巧：要查看當前發布的版本，執行 npm view openclaw version。

然後重啟 + 重新執行 doctor：

openclaw doctor
openclaw gateway restart

鎖定（原始碼）依日期

選擇某日期的 commit（範例：「2026-01-01 時 main 的狀態」）：

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"

然後重新安裝相依套件 + 重啟：

pnpm install
pnpm build
openclaw gateway restart

要回到最新版本：

git checkout main
git pull

遇到困難時

再次執行 openclaw doctor 並仔細閱讀輸出（通常會告訴你修復方式）。
參考：疑難排解
在 Discord 上詢問：https://discord.gg/clawd

更新