openclaw update

更新 OpenClaw，並在 stable/extended-stable/beta/dev 頻道之間切換。

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

用法

openclaw updateopenclaw update statusopenclaw update repairopenclaw update wizardopenclaw update --channel extended-stableopenclaw 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

openclaw --update 會改寫為 openclaw update（適用於 shell 和 啟動器指令碼）。

選項

沒有 --verbose 旗標。請使用 --dry-run 預覽預定動作、 使用 --json 取得機器可讀的結果，並使用 openclaw update status --json 僅查看頻道/可用性。閘道主控台詳細程度（--verbose）與 檔案日誌層級（logging.level: "debug"/"trace"）是彼此獨立的控制項；請參閱 閘道記錄。

update status

顯示目前的更新頻道、git 標籤/分支/SHA（僅限原始碼簽出）， 以及更新可用性。

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

對於 extended-stable 套件安裝，狀態檢查會執行與前景更新相同的公開選擇器 和確切套件驗證。當已安裝版本較新時，它可能會回報 ahead of extended-stable。JSON 失敗結果包含 registry.reason（selector_missing、selector_query_failed、 exact_package_mismatch 或 unsupported_git_channel）。

update repair

核心套件已變更，但後續修復工作未順利完成時， 重新執行更新完成程序。當 openclaw update 已安裝新的核心套件， 但核心更新後的外掛同步、受管理 npm 外掛中繼資料、登錄檔重新整理或 Doctor 修復 未能收斂時，這是受支援的復原途徑。

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

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

update wizard

互動式流程，用於選擇更新頻道，並確認之後是否重新啟動 閘道（預設會重新啟動）。在非 git 簽出的環境中選取 dev， 系統會提供建立簽出的選項。

功能說明

明確切換頻道（--channel ...）也會使安裝方式 保持一致：

• dev -> 確保有 git 簽出（預設為 ~/openclaw；若已設定 OPENCLAW_HOME，則為 $OPENCLAW_HOME/openclaw；可使用 OPENCLAW_GIT_DIR 覆寫），更新該簽出，並從該 簽出安裝全域命令列介面。
• stable -> 使用 latest 從 npm 安裝。
• extended-stable -> 解析公開 npm extended-stable 選擇器、 驗證確切選取的套件，並安裝該確切版本。它 不會後援至其他選擇器，且 Git 簽出不支援此頻道。
• beta -> 優先使用 npm dist-tag beta；當 beta 不存在或早於目前的穩定版本時，後援至 latest。

重新啟動交接

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

儲存的延伸穩定版選擇，會在啟用 update.checkOnStart 時於啟動時以唯讀方式檢查，並每 24 小時提供更新提示。這些檢查絕不會套用更新、啟動移交、重新啟動閘道、使用穩定版的延遲／抖動機制，或採用測試版的輪詢頻率。明確的前景更新、儲存了 update.channel: "extended-stable" 的無參數前景更新、隨選狀態查詢，以及其受管理的閘道移交仍受支援。

當已安裝本機受管理的閘道服務且已啟用重新啟動時，套件管理器與 Git 簽出更新會在取代套件樹或修改簽出內容／建置輸出之前，先停止執行中的服務。更新程式接著會重新整理服務中繼資料、重新啟動服務，並驗證重新啟動的閘道，然後才回報 Gateway: restarted and verified.。套件管理器更新還會驗證重新啟動的閘道回報預期的套件版本；Git 簽出更新則會在重新建置後驗證閘道健康狀態與服務就緒狀態。

在 macOS 上，更新後檢查也會驗證作用中設定檔的 LaunchAgent 已載入／執行，且所設定的迴路位址連接埠狀態正常。如果已安裝 plist，但 launchd 並未監管它，OpenClaw 會自動重新啟動 LaunchAgent，並再次執行健康狀態／版本／頻道就緒檢查（全新啟動會直接載入 RunAtLoad 工作，因此復原程序不會立即對剛啟動的閘道執行 kickstart -k）。如果閘道仍未恢復正常，命令會以非零狀態結束，並列印重新啟動記錄路徑，以及重新啟動、重新安裝與套件回復指示。

如果無法執行重新啟動，命令會列印 Gateway: restart skipped (...) 或 Gateway: restart failed: ...，並提示手動執行 openclaw gateway restart。使用 --no-restart 時，仍會執行套件取代或 Git 重新建置，但不會停止或重新啟動受管理的服務，因此執行中的閘道會繼續使用舊程式碼，直到你手動重新啟動為止。

控制平面回應格式

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

• 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_SYSTEMD_UNIT 單元識別資訊，不能只依賴環境中的 systemd 程序標記）。回應會包含 handoff.command，也就是要從閘道外部執行的 shell 命令。
• ok: false、result.reason: "managed-service-handoff-failed"：閘道嘗試建立移交，但無法啟動分離式輔助程式。

sentinel 承載內容會在閘道結束前寫入，而命令列介面移交會在受管理服務重新啟動的健康檢查完成後，更新同一個重新啟動 sentinel。移交期間，sentinel 可包含 stats.reason: "restart-health-pending"，且不含成功續行資訊；重新啟動的閘道會輪詢該 sentinel，只有在命令列介面驗證服務健康狀態並以最終 ok 結果重寫 sentinel 後，才會觸發續行。當該 sentinel 處於待處理或失敗狀態時，openclaw status 與 openclaw status --all 會顯示 Update restart 列，而 update.status 會重新整理並傳回最新的 sentinel。

Git 簽出流程

頻道選擇

• stable：簽出最新的非測試版標籤，然後建置並執行 doctor。
• beta：優先使用最新的 -beta 標籤；如果測試版不存在或較舊，則回退至最新的穩定版標籤。
• dev：簽出 main，然後擷取並重定基底。
• extended-stable：Git 簽出不支援；不會修改簽出內容。

更新步驟

外掛同步詳細資料

在測試版頻道上，遵循預設／最新版本線的受追蹤 npm 與 ClawHub 外掛安裝項目，會先嘗試外掛的 @beta 版本。如果外掛沒有測試版，OpenClaw 會回退至已記錄的預設／最新規格並回報警告。對於 npm 外掛，如果測試版套件存在但未通過安裝驗證，OpenClaw 也會回退。這些回退警告不會使核心更新失敗。確切版本與明確標籤絕不會被改寫。

延伸穩定版核心更新成功後，核心後外掛完整性與收斂會以符合資格的官方 npm 外掛為目標，並使用與已安裝核心完全相同的版本。對於預設／latest 意圖，OpenClaw 不會查詢外掛的 @extended-stable，也不會回退至 npm latest；它會從已安裝的核心推導套件版本。明確的版本固定、明確的非 latest 標籤、第三方套件與非 npm 來源，會保留其現有意圖。

對於套件管理器安裝，openclaw update 會在叫用套件管理器之前解析目標套件版本。npm 全域安裝採用分階段安裝：OpenClaw 會將新套件安裝到暫存的 npm 前置路徑，在其中驗證封裝的 dist 清單，然後將該乾淨套件樹置換至實際的全域前置路徑。如果驗證失敗，更新後的 doctor、外掛同步與重新啟動工作都不會從可疑的套件樹執行。即使已安裝版本已符合目標，命令仍會重新整理全域套件安裝，然後執行外掛同步、核心命令補全重新整理，以及重新啟動工作。如此可使封裝的附屬元件與頻道所管理的外掛記錄，和已安裝的 OpenClaw 組建保持一致，同時將完整的外掛命令補全重建留給明確執行的 openclaw completion --write-state。

相關內容

• openclaw doctor（在 Git 簽出上會先提議執行更新）
• 開發頻道
• 更新
• 命令列介面參考