更新

讓 OpenClaw 保持最新狀態。

# 建議使用：openclaw update

最快的更新方式。它會偵測你的安裝類型（npm 或 git）、擷取最新版本、執行 openclaw doctor，並重新啟動 Gateway。

openclaw update

若要切換頻道或指定特定版本：

openclaw update --channel beta
openclaw update --channel dev
openclaw update --tag main
openclaw update --dry-run   # preview without applying

openclaw update 不接受 --verbose。若要進行更新診斷，請使用 --dry-run 預覽計畫執行的動作、使用 --json 取得結構化結果，或使用 openclaw update status --json 檢查頻道與可用性狀態。 安裝程式有自己的 --verbose 旗標，但該旗標不是 openclaw update 的一部分。

--channel beta 會優先使用 beta，但當 beta 標籤不存在或早於最新穩定版時，執行階段會退回 stable/latest。若你想要原始 npm beta dist-tag 來進行一次性套件更新，請使用 --tag beta。

請參閱開發頻道了解頻道語意。

# 在 npm 與 git 安裝之間切換

當你想變更安裝類型時，請使用頻道。更新程式會保留你的 狀態、設定、認證資料和 ~/.openclaw 中的工作區；它只會變更 CLI 與 Gateway 使用的 OpenClaw 程式碼安裝來源。

# npm package install -> editable git checkout
openclaw update --channel dev

# git checkout -> npm package install
openclaw update --channel stable

請先使用 --dry-run 執行，以預覽確切的安裝模式切換：

openclaw update --channel dev --dry-run
openclaw update --channel stable --dry-run

dev 頻道會確保存在 git checkout、建置它，並從該 checkout 安裝全域 CLI。 stable 與 beta 頻道使用套件安裝。若 Gateway 已安裝，openclaw update 會重新整理服務中繼資料，並在你傳入 --no-restart 以外的情況下重新啟動它。

# 替代方式：重新執行安裝程式

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

加入 --no-onboard 可略過 onboarding。若要透過安裝程式強制使用特定安裝類型，請傳入 --install-method git --no-onboard 或 --install-method npm --no-onboard。

如果 openclaw update 在 npm 套件安裝階段後失敗，請重新執行 安裝程式。安裝程式不會呼叫舊的更新程式；它會直接執行全域 套件安裝，並且可以復原部分更新完成的 npm 安裝。

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

若要將復原固定到特定版本或 dist-tag，請加入 --version：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>

# 替代方式：手動使用 npm、pnpm 或 bun

npm i -g openclaw@latest

對於受監督的安裝，建議使用 openclaw update，因為它可以協調 套件替換與正在執行的 Gateway 服務。如果你在受管理的 Gateway 執行中手動更新，請在套件管理器完成後立即重新啟動 Gateway，以免舊程序繼續從已替換的套件檔案提供服務。

當 openclaw update 管理全域 npm 安裝時，它會先將目標安裝到 臨時 npm prefix，驗證封裝的 dist 清單，然後將乾淨的套件樹 替換到真正的全域 prefix。這可避免 npm 將新套件覆蓋到舊套件留下的過期檔案上。如果安裝命令失敗，OpenClaw 會使用 --omit=optional 重試一次。該重試有助於原生選用相依套件無法編譯的主機，同時在備援也失敗時仍保留原始失敗資訊可見。

pnpm add -g openclaw@latest

bun add -g openclaw@latest

# 進階 npm 安裝主題

ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp

# 自動更新程式

自動更新程式預設為關閉。請在 ~/.openclaw/openclaw.json 中啟用：

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

Gateway 也會在啟動時記錄更新提示（可用 update.checkOnStart: false 停用）。 若要降級或進行事件復原，請在 Gateway 環境中設定 OPENCLAW_NO_AUTO_UPDATE=1，即使已設定 update.auto.enabled 也會阻止自動套用。除非也停用 update.checkOnStart，否則啟動更新提示仍可能執行。

透過即時 Gateway control-plane handler 要求的套件管理器更新，會在套件替換後強制進行不延後、無冷卻時間的更新重新啟動。這可避免舊的記憶體內程序停留太久，並從已被替換的套件樹 lazy-load chunks。Shell openclaw update 仍是受監督安裝的建議路徑，因為它可以在更新前後停止並重新啟動服務。

# 更新後

openclaw doctor

openclaw gateway restart

openclaw health

# 回復

# 固定版本（npm）

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart

# 固定 commit（原始碼）

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，並仔細閱讀輸出。
• 對於原始碼 checkout 上的 openclaw update --channel dev，更新程式會在需要時自動 bootstrap pnpm。如果你看到 pnpm/corepack bootstrap 錯誤，請手動安裝 pnpm（或重新啟用 corepack），然後重新執行更新。
• 檢查：疑難排解
• 在 Discord 詢問：https://discord.gg/clawd

# 相關

• 安裝總覽：所有安裝方法。
• Doctor：更新後的健康檢查。
• 遷移：主要版本遷移指南。