更新中

讓 OpenClaw 保持最新狀態。

如需 Docker、Podman 與 Kubernetes 映像檔替換的相關資訊，請參閱 升級容器映像檔。閘道會在就緒之前執行啟動安全的升級工作；若掛載的狀態需要手動修復，則會結束。

建議方式：openclaw update

偵測安裝類型（npm、pnpm、Bun 或 git）、取得最新版本、執行 openclaw doctor，並重新啟動閘道。

openclaw update

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

openclaw update --channel betaopenclaw update --channel extended-stableopenclaw update --channel devopenclaw update --dry-run   # 預覽但不套用

openclaw update 沒有 --verbose 旗標（安裝程式才有）。若要進行診斷，請使用 --dry-run 預覽規劃的動作、使用 --json 取得結構化結果，或使用 openclaw update status --json 檢查頻道與可用性狀態。

--channel beta 會優先使用 beta npm dist-tag，但若 beta 標籤不存在，或其版本比最新的穩定版更舊，則會退回 stable/latest。 若要執行一次性套件更新並固定使用原始 npm beta dist-tag，請改用 --tag beta。

--channel extended-stable 僅適用於套件，且安裝仍只能在前景執行。OpenClaw 會讀取公開 npm 的 extended-stable 選擇器、驗證選定的確切套件，並安裝該確切版本。若登錄資料缺失或不一致，操作會採取封閉式失敗；絕不會退回 latest。 如果選定版本比已安裝版本更舊，仍會套用一般的降級確認。命令列介面會在核心更新成功後保存頻道；直接執行 npm install -g openclaw@extended-stable 不會更新 update.channel。 核心切換完成後，使用 bare/default 或 latest 意圖且符合資格的官方 npm 外掛，會收斂至該確切核心版本。確切版本固定、明確的非 latest 標籤、第三方外掛及非 npm 來源均維持不變。 由目前 OpenClaw 版本建立的目錄安裝會保留該預設意圖。僅包含確切版本的舊記錄會繼續固定，因為 OpenClaw 無法安全區分舊的自動固定與使用者固定；請在 extended-stable 頻道執行一次 openclaw plugins update @openclaw/name，讓該外掛重新採用確切核心版本追蹤。

--channel dev 會提供持續移動的 GitHub main 簽出。若要執行一次性套件更新，--tag main 會對應至 github:openclaw/openclaw#main 套件規格，並透過目標套件管理員（npm/pnpm/bun）直接安裝。

對於受管理的外掛，缺少 beta 版本只會產生警告，不會導致失敗：核心更新仍可成功，而外掛會退回其記錄的 default/latest 版本。

如需頻道語意的相關資訊，請參閱發行頻道。

在 npm 與 git 安裝之間切換

使用頻道變更安裝類型。更新程式會保留 ~/.openclaw 中的狀態、設定、認證資訊與工作區；它只會變更命令列介面與閘道所使用的 OpenClaw 程式碼安裝。

# npm 套件安裝 -> 可編輯的 git 簽出openclaw update --channel dev # git 簽出 -> npm 套件安裝openclaw update --channel stable

先預覽安裝模式切換：

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

dev 會確保存在 git 簽出、建置該簽出，並從該簽出安裝全域命令列介面。stable、extended-stable 與 beta 頻道使用套件安裝。 在 git 簽出中會拒絕 extended-stable，且不會修改或轉換該簽出。如果閘道已安裝，openclaw update 會重新整理服務中繼資料並重新啟動，除非你傳入 --no-restart。

對於具有受管理閘道服務的套件安裝，openclaw update 會以該服務使用的套件根目錄為目標。如果殼層中的 openclaw 命令來自其他安裝，更新程式會印出兩個根目錄與受管理服務的 Node 路徑，並在替換套件前，根據目標版本的 engines.node 要求檢查該 Node 版本。

原始碼簽出伺服器（參考指令碼）

直接從伺服器上的 git 簽出執行閘道的團隊，可以在該簽出內使用 scripts/update-gateway.sh 進行更新。這是高效率原始碼伺服器更新的參考實作：它會還原 pnpm build 改寫的受追蹤建置輸出、在存在任何其他本機變更時採取封閉式失敗、快轉 main（或將本機伺服器分支變基至 origin/main）、安裝相依套件、進行乾淨建置，並重新啟動閘道。

ssh you@server 'cd /path/to/openclaw && scripts/update-gateway.sh'

針對自訂服務單元覆寫重新啟動命令，或完全略過重新啟動：

OPENCLAW_UPDATE_RESTART_CMD='systemctl --user restart openclaw-gateway.service' scripts/update-gateway.shOPENCLAW_UPDATE_RESTART_CMD='' scripts/update-gateway.sh

對於一般的單一使用者原始碼安裝，請改用 openclaw update --channel dev——它會替你管理簽出、建置及閘道重新啟動。

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

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

加入 --no-onboard 可略過初始設定。若要強制使用特定安裝類型，請傳入 --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

使用 --version 將復原固定至特定版本或 dist-tag：

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：它可以協調套件切換與正在執行的閘道服務。如果你要手動更新受監督的安裝，請先停止受管理的閘道。套件管理員會就地替換檔案，否則正在執行的閘道可能會在切換過程中嘗試載入核心或外掛檔案。套件管理員完成後，請重新啟動閘道，使其載入新的安裝。

對於由 root 擁有的 Linux 系統全域安裝，如果 openclaw update 因 EACCES 而失敗，請使用系統 npm 進行復原，並在手動替換期間保持閘道停止。請使用平常用於該閘道的相同設定檔旗標／環境。將 /usr/bin/npm 替換為主機上擁有 root 全域前綴的系統 npm：

openclaw gateway stopsudo /usr/bin/npm i -g openclaw@latestopenclaw gateway install --forceopenclaw gateway restart

接著驗證：

openclaw --versioncurl -fsS http://127.0.0.1:18789/readyzopenclaw plugins list --jsonopenclaw gateway status --deep --jsonopenclaw doctor --lint --json

當 openclaw update 管理全域 npm 安裝時，它會先將目標安裝到暫時的 npm 前綴。候選套件會在 preinstall 期間驗證主機 Node 版本；只有通過後，OpenClaw 才會驗證已封裝的 dist 清單，並將乾淨的套件樹切換至實際的全域前綴。預期清單不包含已封裝的完成防護項目，且僅在 preinstall 成功後才會將其移除，因此略過生命週期指令碼也會在切換前失敗。 在 npm 12 與更新版本中，更新程式只會允許候選 OpenClaw 的生命週期；遞移相依套件的指令碼仍會遭封鎖。這可避免 npm 將新套件覆蓋至舊套件殘留的檔案上。如果安裝命令失敗，OpenClaw 會使用 --omit=optional 重試一次，這有助於無法編譯原生選用相依套件的主機。

由 OpenClaw 管理的 npm 更新與外掛更新命令，也會為子 npm 處理程序清除 npm 的 min-release-age 供應鏈隔離設定（或較舊的 before 設定鍵）。該政策是為了一般性保護而存在，但明確執行 OpenClaw 更新表示「立即安裝選定的版本」。

pnpm add -g openclaw@latest

如果 pnpm 11 安裝了 OpenClaw 2026.7.1，請手動執行一次該命令。該版本早於 pnpm 11 的隔離式全域套件配置，因此其更新程式可能會將另一個 npm 安裝誤認為正在執行的命令列介面。後續版本會保留 pnpm 擁有權，並在更新期間追蹤替換套件的根目錄。它們也會使用擁有者套件管理員回報的全域 bin 目錄，並在發生修改前停止：例如可用的 pnpm 命令回報另一個全域根目錄或主要版本，或叫用套件已成為孤立套件，或不是該位置唯一有效的 OpenClaw 安裝。

如果 OpenClaw 與其他套件共用 pnpm 11 全域安裝群組，自動更新程式會在變更該群組前停止。請手動更新原始的逗號分隔群組，以維持其同層套件與建置政策不變。

bun add -g openclaw@latest

進階 npm 安裝主題

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

自動更新程式

預設關閉。請在 ~/.openclaw/openclaw.json 中啟用：

{  update: {    channel: "stable",    auto: {      enabled: true,    },  },}

閘道也會在啟動時記錄更新提示（可使用 update.checkOnStart: false 停用）。已儲存的延伸穩定版選擇會使用此 唯讀提示路徑以及現有的 24 小時提示間隔，但絕不會叫用 自動安裝、交接、重新啟動、穩定版延遲／抖動或 Beta 版輪詢。 若要降級或進行事件復原，請在閘道環境中設定 OPENCLAW_NO_AUTO_UPDATE=1，即使已設定 update.auto.enabled，也能封鎖自動套用。除非同時停用 update.checkOnStart，否則啟動更新提示仍可執行。

透過即時閘道控制平面 （update.run）要求的套件管理器更新，不會取代執行中閘道 程序內的套件樹狀結構。在受管理的服務安裝中，閘道會啟動分離式交接、 結束程序，並讓一般的 openclaw update --yes --json 命令列介面路徑停止 服務、取代套件、重新整理服務中繼資料、重新啟動、驗證 閘道版本與可連線性，並在可行時復原已安裝但未載入的 macOS LaunchAgent。如果閘道無法安全進行該交接， update.run 會回報安全的 shell 命令，而不會在程序內執行套件 管理器。

控制介面側邊欄的更新卡片會在可直接啟動此 update.run 流程時顯示 更新閘道。這涵蓋瀏覽器託管的控制介面、遠端 閘道，以及手動管理的本機閘道。

在已簽署的 macOS App 中，由本機 App 擁有的閘道會將該卡片改為 更新 Mac App 與閘道。Sparkle 會先更新 App；重新啟動後， App 會執行 openclaw update --tag <app-version> --json、重新啟動其閘道， 並在設定流程樣式的進度視窗中驗證健康狀態。只有在該受管理閘道需要更新、修復或安裝時， 才會顯示此視窗；僅更新 App 時，會重新啟動並直接進入 App。失敗詳細資料會持續顯示，並提供重試、更新指南及 Discord 動作。App 絕不會對遠端或由外部管理的閘道使用此協調 路徑、絕不會降級較新的閘道，也絕不會覆寫 extended-stable 頻道固定設定。

更新成功時，App 會為最近一個曾與真實使用者／頻道互動的 頂層直接工作階段排入一次性歡迎事件。排程執行、 心跳偵測及僅限背景的工作階段更新不會改變該選擇。在 遠端模式下，App 只會更新其本機 Mac 節點執行階段，而且只有在連線的遠端閘道版本 至少與 App 一樣新時才會傳送該事件。

更新後

openclaw doctor

openclaw gateway restart

openclaw health

復原

復原分為兩個層級：

1. 重新安裝較舊的 OpenClaw 程式碼，同時保留目前狀態。
2. 只有當較舊的程式碼無法使用已遷移的 設定或資料庫時，才還原更新前的狀態。

請先僅復原程式碼。還原狀態會捨棄 備份後所做的變更。

更新前：建立已驗證的備份

openclaw update 會保留一份自動建立的更新前設定副本，但不會 建立完整的狀態復原點。進行重大更新前，請明確建立一個復原點：

mkdir -p ~/Backups/openclawopenclaw backup create --output ~/Backups/openclaw --verify

封存檔資訊清單會記錄 OpenClaw 版本及備份中包含的來源路徑。 封存檔可能包含認證資訊、驗證設定檔及頻道 狀態，因此請以僅擁有者可存取的權限儲存，並採用與 即時狀態目錄相同的保護措施。關於包含及刻意 省略的檔案，請參閱備份。

若要建立逐位元組一致，且包含可攜式封存檔所省略之揮發性成品的復原點， 請停止閘道，並使用平台提供的檔案系統、磁碟區或 VM 快照。

復原套件安裝

列出已發布的版本，然後預覽並安裝已知正常的版本：

npm view openclaw versions --jsonopenclaw update --tag <known-good-version> --dry-runopenclaw update --tag <known-good-version>

建議優先使用 openclaw update --tag，而非直接透過套件管理器安裝。它會 偵測降級、要求確認、對已安裝的目標執行受管理的外掛收斂 及相容性檢查、重新整理服務 中繼資料、重新啟動閘道，並驗證執行中的版本。如果儲存的 頻道是 extended-stable，請使用 --channel stable --tag <known-good-version>，因為一次性的確切標記無法 與 extended-stable 選擇器搭配使用。

套件更新會在啟用前暫存並驗證候選版本。如果 檔案系統交換或命令墊片取代失敗，OpenClaw 會自動還原舊 套件。成功交換後，若稍後發生閘道健康狀態失敗， 系統會回報先前版本與手動復原指示，而不會 再次自動取代套件。

如果命令列介面更新路徑無法使用，請使用擁有目前閘道的相同套件管理器及安裝 範圍：

openclaw gateway stopnpm i -g openclaw@<known-good-version>openclaw gateway install --forceopenclaw gateway restart

當安裝由對應的管理器擁有時，請將 npm 替換為 pnpm 或 bun。進行 事件復原期間，請在閘道環境中設定 OPENCLAW_NO_AUTO_UPDATE=1，避免已啟用的自動更新程式立即套用 較新的版本。

復原原始碼簽出

使用乾淨的簽出，並選擇已知正常的標記或提交：

git fetch --all --tagsgit checkout --detach <known-good-tag-or-commit>pnpm install && pnpm buildopenclaw gateway restart

若要回到最新版本：git checkout main && git pull。

在 git 更新開始後，如果相依套件安裝、建置、介面建置或 doctor 失敗， 更新程式會自動將 git 簽出還原至先前的分支與 SHA。若你有意選擇 較舊的提交，仍需手動簽出。

跨越工作階段 SQLite 遷移進行降級

啟動較舊且以檔案為基礎的 OpenClaw 版本前，請使用目前的命令列介面 還原已封存的舊版對話記錄成品：

openclaw gateway stopopenclaw doctor --session-sqlite restore --session-sqlite-all-agents

這不會刪除 SQLite 資料。在 SQLite 遷移後建立的工作階段 只存在於 SQLite 中，不會出現在較舊的執行階段。請參閱 工作階段 SQLite 遷移後的降級。

只在必要時還原狀態

如果較舊的程式碼無法讀取較新的設定或資料庫結構描述，請停止 閘道並還原已驗證的更新前檔案系統、磁碟區或 VM 快照。 還原前請另行保留目前狀態，因為這會移除 快照後所做的變更。

廣泛的 openclaw backup create 封存檔支援建立與驗證，但 不支援就地啟用整個封存檔。請將廣泛封存檔解壓縮至暫存 目錄，並使用其 manifest.json 來源至封存檔對應進行離線 還原。openclaw backup sqlite restore 同樣會將已驗證的資料庫寫入 新的目標；啟用該目標仍是明確的離線操作者 步驟。

驗證復原

openclaw --versionopenclaw healthopenclaw plugins list --jsonopenclaw gateway status --deep --jsonopenclaw doctor --lint --json

如果遇到問題

• 再次執行 openclaw doctor，並仔細閱讀輸出。
• 針對原始碼簽出上的 openclaw update --channel dev，更新程式會在需要時自動啟動 pnpm。如果你看到 pnpm/corepack 啟動錯誤，請手動安裝 pnpm（或重新啟用 corepack），然後重新執行更新。
• 查看：疑難排解
• 在 Discord 中提問：https://discord.gg/clawd

相關內容

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