openclaw update

安全地更新 OpenClaw，並在 stable/beta/dev 通道之間切換。

如果你是透過 npm/pnpm/bun 安裝（全域安裝，沒有 git 中繼資料）， 更新會透過更新中的套件管理器流程進行。

用法

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel betaopenclaw update --channel devopenclaw update --tag betaopenclaw update --tag mainopenclaw update --dry-runopenclaw update --no-restartopenclaw update --yesopenclaw update --acknowledge-clawhub-riskopenclaw update --jsonopenclaw --update

選項

• --no-restart：成功更新後略過重新啟動閘道服務。會重新啟動閘道的套件管理器更新，會先確認重新啟動後的服務回報預期的更新版本，命令才會成功。
• --channel <stable|beta|dev>：設定更新通道（git + npm；會保存在設定中）。
• --tag <dist-tag|version|spec>：只針對這次更新覆寫套件目標。對於套件安裝，main 會對應到 github:openclaw/openclaw#main；GitHub/git 來源規格會先打包成暫時的 tarball，再進行分階段的全域 npm 安裝。
• --dry-run：預覽規劃的更新動作（通道/標籤/目標/重新啟動流程），不會寫入設定、安裝、同步外掛或重新啟動。
• --json：列印機器可讀的 UpdateRunResult JSON，包括核心更新成功後，當損毀或無法載入的受管理外掛需要修復時的 postUpdate.plugins.warnings、外掛沒有 beta 版時的 beta 通道外掛備援詳細資料，以及更新後外掛同步期間偵測到 npm 外掛成品漂移時的 postUpdate.plugins.integrityDrifts。
• --timeout <seconds>：每個步驟的逾時時間（預設為 1800 秒）。
• --yes：略過確認提示（例如降版確認）。
• --acknowledge-clawhub-risk：在檢閱社群 ClawHub 信任警告後，允許更新後外掛同步在沒有互動提示的情況下繼續。若未使用此選項，當 OpenClaw 無法提示時，有風險的社群 ClawHub 外掛發行版會被略過並保持不變。官方 ClawHub 套件和內建 OpenClaw 外掛來源會略過這個發行版信任提示。

openclaw update 沒有 --verbose 旗標。使用 --dry-run 預覽規劃的通道/標籤/安裝/重新啟動動作，使用 --json 取得機器可讀結果；如果只需要通道和可用性詳細資料，請使用 openclaw update status --json。如果你正在偵錯更新期間的閘道日誌，主控台詳細程度和檔案日誌等級是分開的：閘道 --verbose 會影響終端機/WebSocket 輸出，而檔案日誌需要在設定中使用 logging.level: "debug" 或 "trace"。請參閱閘道日誌。

update status

顯示作用中的更新通道 + git 標籤/分支/SHA（對於來源 checkout），以及更新可用性。

openclaw update statusopenclaw update status --jsonopenclaw update status --timeout 10

選項：

• --json：列印機器可讀的狀態 JSON。
• --timeout <seconds>：檢查的逾時時間（預設為 3 秒）。

update repair

在核心套件已經變更，但後續修復工作未能乾淨完成後，重新執行更新收尾。當 openclaw update 已安裝新的核心套件，但核心後的外掛同步、受管理 npm 外掛中繼資料、登錄檔重新整理或 doctor 修復仍需要收斂時，這是受支援的復原路徑。

openclaw update repairopenclaw update repair --channel betaopenclaw update repair --acknowledge-clawhub-riskopenclaw update repair --json

選項：

• --channel <stable|beta|dev>：在修復前保存更新通道，並針對該通道執行外掛收斂。
• --json：列印機器可讀的收尾 JSON。
• --timeout <seconds>：修復步驟的逾時時間（預設 1800）。
• --yes：略過確認提示。
• --acknowledge-clawhub-risk：在檢閱社群 ClawHub 信任警告後，允許修復期間的外掛收斂在沒有互動提示的情況下繼續。官方 ClawHub 套件和內建 OpenClaw 外掛來源會略過這個發行版信任提示。
• --no-restart：為了與更新命令一致而接受；修復永遠不會重新啟動閘道。

openclaw update repair 會執行 openclaw doctor --fix、重新載入已修復的設定和安裝記錄、為作用中的更新通道同步已追蹤的外掛、更新受管理的 npm 外掛安裝、修復遺失的已設定外掛承載內容、重新整理外掛登錄檔，並寫入已收斂的安裝記錄中繼資料。它不會安裝新的核心套件，也不會重新啟動閘道。

update wizard

互動式流程，可選擇更新通道，並確認更新後是否要重新啟動閘道（預設會重新啟動）。如果你選擇 dev 但沒有 git checkout，它會提議建立一個。

選項：

• --timeout <seconds>：每個更新步驟的逾時時間（預設 1800）

它會做什麼

當你明確切換通道（--channel ...）時，OpenClaw 也會保持安裝方式一致：

• dev → 確保有 git checkout（預設：~/openclaw，或在設定 OPENCLAW_HOME 時使用 $OPENCLAW_HOME/openclaw；可用 OPENCLAW_GIT_DIR 覆寫），更新它，並從該 checkout 安裝全域命令列介面。
• stable → 使用 latest 從 npm 安裝。
• beta → 優先使用 npm dist-tag beta，但當 beta 缺失或比目前 stable 發行版更舊時，會退回 latest。

閘道核心自動更新器（透過設定啟用時）會在即時閘道請求處理常式之外啟動命令列介面更新路徑。控制平面 update.run 套件管理器更新和受監督的 git-checkout 更新，也會使用受管理服務交接，而不是在即時閘道程序內替換套件樹或重建 dist/。閘道會啟動分離的輔助程序、退出，然後輔助程序會從閘道程序樹之外執行一般的 openclaw update --yes --json 命令列介面路徑。如果該交接不可用，update.run 會回傳結構化回應，其中包含可手動執行的安全 shell 命令。

對於套件管理器安裝，openclaw update 會先解析目標套件版本，再呼叫套件管理器。npm 全域安裝會使用分階段安裝：OpenClaw 會將新套件安裝到暫時的 npm 前綴、在那裡驗證封裝的 dist 清單，然後將該乾淨的套件樹替換到實際的全域前綴。如果驗證失敗，更新後 doctor、外掛同步和重新啟動工作不會從可疑的樹執行。即使已安裝版本已符合目標，命令仍會重新整理全域套件安裝，然後執行外掛同步、核心命令補全重新整理，以及重新啟動工作。這會讓封裝的 sidecar 和通道擁有的外掛記錄與已安裝的 OpenClaw 建置保持一致，同時將完整外掛命令補全重建留給明確的 openclaw completion --write-state 執行。

當已安裝本機受管理閘道服務且啟用重新啟動時，套件管理器和 git-checkout 更新會先停止正在執行的服務，再替換套件樹或變更 checkout/建置輸出。更新器接著會從更新後的安裝重新整理服務中繼資料、重新啟動服務，並在回報 Gateway: restarted and verified. 前驗證重新啟動後的閘道。套件管理器更新還會額外確認重新啟動後的閘道回報預期的套件版本；git-checkout 更新則會在重建後驗證 gateway 健康狀態和服務就緒狀態。在 macOS 上，更新後檢查也會驗證 LaunchAgent 已針對作用中設定檔載入/執行，且設定的 loopback 連接埠健康。如果 plist 已安裝但 launchd 未監督它，OpenClaw 會自動重新 bootstrap LaunchAgent，然後重新執行健康狀態/版本/通道就緒檢查。新的 bootstrap 會直接載入 RunAtLoad 作業，因此更新復原不會立即對新產生的閘道執行 kickstart -k。如果閘道仍未變得健康，命令會以非零狀態結束，並列印重新啟動日誌路徑，以及明確的重新啟動、重新安裝和套件回復指示。如果無法執行重新啟動，命令會列印 Gateway: restart skipped (...) 或 Gateway: restart failed: ...，並附上手動 openclaw gateway restart 提示。使用 --no-restart 時，套件替換或 git 重建仍會執行，但受管理服務不會被停止或重新啟動，因此正在執行的閘道可能會繼續使用舊程式碼，直到你手動重新啟動它。

控制平面回應形狀

當透過閘道控制平面在套件管理器安裝或受監督的 git checkout 上呼叫 update.run 時，處理常式會將交接啟動與閘道退出後繼續進行的命令列介面更新分開回報：

• ok: true、result.status: "skipped"、result.reason: "managed-service-handoff-started"，以及 handoff.status: "started" 表示閘道已建立受管理服務交接，並排程自己的重新啟動，讓分離的輔助程序可以在即時服務程序之外執行 openclaw update --yes --json。
• ok: false、result.reason: "managed-service-handoff-unavailable"，以及 handoff.status: "unavailable" 表示 OpenClaw 找不到監督服務邊界和持久服務身分，因此無法安全交接。例如，systemd 交接需要 OpenClaw unit 身分（OPENCLAW_SYSTEMD_UNIT），而不只是環境中的 systemd 程序標記。回應包含 handoff.command，也就是要從閘道之外執行的 shell 命令。
• ok: false、result.reason: "managed-service-handoff-failed" 表示閘道嘗試建立交接，但無法產生分離的輔助程序。

sentinel 承載內容仍會在閘道退出前寫入，而命令列介面交接會在受管理服務重新啟動健康檢查完成後，更新同一個重新啟動 sentinel。交接期間，sentinel 可能帶有 stats.reason: "restart-health-pending"，且沒有成功延續；重新啟動後的閘道會持續輪詢它，並且只會在命令列介面已驗證服務健康狀態、並用最終 ok 結果重寫 sentinel 後，才觸發延續。openclaw status 和 openclaw status --all 會在該 sentinel 擱置或失敗時顯示 Update restart 列，而 update.status 會重新整理並回傳最新的 sentinel。

Git checkout 流程

通道選擇

• stable：checkout 最新的非 beta 標籤，然後建置並執行 doctor。
• beta：優先使用最新的 -beta 標籤，但當 beta 缺失或較舊時，退回最新的 stable 標籤。
• dev：checkout main，然後 fetch 並 rebase。

更新步驟

在 beta 更新通道上，遵循預設/最新版路線的受追蹤 npm 與 ClawHub 外掛安裝，會先嘗試外掛 @beta 發行版。如果外掛沒有 beta 發行版，OpenClaw 會退回到已記錄的預設/最新版規格，並將其回報為警告。對於 npm 外掛，當 beta 套件存在但安裝驗證失敗時，OpenClaw 也會退回。這些外掛後備警告不會讓核心更新失敗。精確版本與明確標籤不會被改寫。

--update 簡寫

openclaw --update 會重寫為 openclaw update（對 shell 和啟動器指令碼很有用）。

相關

• openclaw doctor（在 git checkout 上會提議先執行更新）
• 開發通道
• 更新
• 命令列介面參考