OpenClaw 2026.10.5 升級：no-restart、snapshot 與 Gateway 驗收

10.5：no-restart 不等於保證服務不中斷#

10.5 stable 的 GitHub release published_at 為 2026-10-18 21<47> UTC，台灣時間是 10 月 19 日 05<47>，未標為 prerelease。不要把較早的 10.5 beta 公告日期當成正式版發布日；下列判讀固定依 10.5 Update CLI 文件。

對 npm、pnpm、bun global 套件安裝，--no-restart 略過的是 updater 管理的 restart 與尾端 readiness 等待。執行中的 Gateway 偵測安裝已被替換，仍會自行重啟；舊 runtime 繼續讀取已替換套件，可能找不到必要 chunks。這個旗標不能當成零停機承諾，也不該用來讓正式長任務在套件替換期間繼續跑。

PR #173409修正上述 package 路徑的回報：套件已安裝成功，但 Gateway readiness 尚未可用或仍回應舊版時，保留成功安裝並附 warning；不把這類觀測直接轉成整次安裝失敗。其他更新失敗仍保留原診斷，不能看到 10.5 就把所有 error 都降級忽略。

10.4：先找失敗階段，再決定是否需要 repair#

10.4 stable 的實際發布時間是 2026-10-16 00<36> UTC，台灣時間為 10 月 16 日 08<36>；版本名稱中的 10.4 不代表 10 月 4 日發布。官方將它列為 10.3 的穩定性修補，沒有新增功能或設定變更。查核範圍固定為這個 release，不把較新 beta 的完整修復清單視為 stable 能力。

先保存原本失敗的 log 與 update status，再做新的 dry-run 或更新。以下是文件檢閱用的唯讀診斷命令，本文未執行：

1
openclaw --version
2
openclaw update status --json
3
openclaw gateway status

10.4 Update CLI 文件提醒，新的嘗試可能取代最新 history 的顯示；保存 lastRun 的 target、失敗階段、原始 updater 版本與 next action，才能對照先前發生的事。分享診斷時先移除憑證和私人路徑。

10.3 卡住的更新，要按失敗階段驗收#

2026.10.3 stable release於 10 月 13 日發布；版本固定的 changelog列出 receipt identity drift、handoff lease 遺失與舊 9.8 activation record 的復原修正。這些是特定更新狀態的修正，不能把任意卡住的 update 都判成同一原因。

先保存原更新 record 與第一個失敗階段，再核對 openclaw --version、openclaw update status 和 openclaw gateway status。將結果分成下列情況，能避免把套件、服務和資料問題混成一次重裝：

10.3 涵蓋 Windows machine-qualified Scheduled Task account、短路徑及 Doctor ancestry 檢查，macOS protected Bun service command，以及 pnpm 12 launcher 的修正。對 pnpm 安裝，尤其要比對 service 命令是否留在 durable install link；PR #170003所處理的是服務路徑的生命週期，shell 裡 CLI 正常不能證明背景 service 的路徑也正常。

Doctor 的資料保留修正包括 legacy auth store 無法讀取時保留 canonical OAuth profile（PR #170256）、不以 replacement character 改寫損壞 UTF-8 memory，以及 path-safety block 時保留 Plugin enabled 設定。這些保障不會補回升級前已經遺失的資料；比對時仍要用原始備份，避免拿經過修復的檔案當唯一基準。

PR #167714另修正 Doctor maintenance 被略過時，openclaw update repair 不應回報成功。自動化驗收應把「必要步驟已執行」列為完成條件；若 record 顯示 skipped 或 recovery 尚未完成，就保留錯誤與復原素材，依 next action 處理，不能用成功文字自行解除維護狀態。

本節於 2026-10-14 檢閱 release、tagged changelog 與上述 PR，沒有執行更新、Doctor、service 重啟或資料還原。查核時也存在 10.5 beta release；本節範圍固定為 10.3 stable，不要求正式環境切換 beta。

10.1 更新後才報錯，先保留版本與失敗階段#

PR #168849說明，已發布的 10.1 updater 在套件替換後載入 cleanup facade，可能過早關閉原本的 shared-state cleanup queue。10.2 所含修正保留舊 updater 需要的相容入口，讓第一次升級能完成；這不是要求使用者手動修改 queue 或設定檔。

Windows 的另一個特定症狀是 post-plugin-doctor-execution-failed，並出現 Unknown shared-state SQLite command。PR #169031補回 10.1 updater 在替換後仍會送出的 pending-migration 唯讀指令。這個修正不代表所有 Plugin Doctor 錯誤都有相同根因。

遇到上述症狀，先保留錯誤階段與 log，確認目前實際版本及 update status。套件可能已換過，不能只因 CLI 報錯就假設「完全沒更新」，更不能刪掉資料目錄重新開始。若仍有 updater 或 recovery 工作，先依該次回報的恢復指引處理；沒有必要重建 Plugin migration 資料來套用這兩項修正。

退出碼 0：分清 skipped、完成與 channel 警告#

10.2 版本的 Update CLI 文件指出，未辨識到 package-manager owner 的安裝可以記錄 skipped、成功退出並保留 Gateway 運作。Docker image、獨立 tarball 或 Yarn global 安裝要依原安裝方式維護；skipped 不代表已安裝目標版本。

PR #169037則保留已記錄的成功 outcome：後續結果發布失敗改為 warning；repair 驗證也會另外列出仍停止或受抑制的 channel，不把它們一律轉成整次更新失敗。disabled 或未設定的 account 不列入這類 runtime warning。

檢查順序如下；前半段是唯讀或 dry-run 診斷，沒有執行更新：

1
openclaw --version
2
openclaw update status
3
openclaw update --dry-run

接著對照原本那次更新回報：

• 顯示 skipped：確認 installation owner 與 next action，透過原安裝方式更新後再核對版本。
• 已完成但有 publication warning：保留 warning，核對已安裝版本與 Gateway runtime，不為了消除顯示而盲目重跑 update。
• 有 stopped／suppressed channel warning：確認預期啟用的 account，再測試一次實際收發。更新完成不能代替 channel 恢復。

CLI 的版本輸出、service 使用的 runtime 與實際任務結果要一起保存。如果目標版本正確但任務仍失敗，沿著 Plugin、provider 或 channel 層追查，保留升級前備份；不要把錯誤訊息變少當成驗收通過。

本文的 9.9 歷史段落於 2026-10-09 查核 2026.9.9 release notes、repair 文件、Telegram Mini App、Update CLI 與 Node requirements。沒有在本機 Gateway 執行升級、Doctor 或訊息測試；以下保留先前版本的適用條件，命令與驗收流程需在自己的隔離環境執行。

先分清 stable、beta 與實際發布日期#

2026-10-13 查核 GitHub 2026.10.2 release，其 published_at 是 2026-10-12 05<34> UTC，台灣時間為 10 月 12 日 13<34>，未標為 prerelease。版本名稱中的 10.2 不能當成 10 月 2 日發布的證據。

後面的外部備份流程是 10.1 引入、於 2026-10-12 查核的功能，9.9、9.8 等段落則保留歷史適用條件。先前查核的 2026.10.5-beta.1仍是預覽版；本文不把它的整份修復清單當成 10.2 stable 已具備的能力。

先用前面的版本、status 與 dry-run 診斷，核對安裝方式、更新 channel 和預計目標。維護 stable 時，beta 公告本身不構成切換 channel 的理由。

10.1 的備份，要驗收到 staging 還原#

10.1 官方 changelog 與 backup 指南說明，完整備份可放到外接磁碟、掛載儲存或 Cloudflare R2，再還原到新的 staging 目錄。排程與 retention 是選用設定；沒有 retention 旗標就不會自動刪除舊備份。

升級前把下列四個條件寫進自己的復原紀錄：

1. 副本是否加密：外部上傳可選 passphrase 加密，明文則需明確選 none。即使上傳有加密，加上 --output 留下的本機 .tar.gz 仍是明文；不要把這份本機檔案當成可公開分享的加密副本。
2. 備份屬於哪個安裝：同時運作的安裝各用獨立 namespace。要接手原 namespace，先停止原 owner；不要為了測試第二台 Gateway 就直接 claim 原備份，讓 retention 混在一起。
3. 復原所需資訊是否齊全：保存原 passphrase、location marker 與 namespace，並讓執行備份的 Gateway 能取得所需 credentials。只有 archive 檔名，不能證明在新主機上可解密與定位原資料。
4. 同一世代資料是否完整：設定、共享資料庫與需要的各 agent 資料庫必須來自同一份備份世代。不能拿新的設定配舊資料庫，也不能混入別份備份的 SQLite -wal、-shm 或 -journal。

這些條件對應實際復原失敗邊界，不是要求先把 R2 接上才可升級。已有本機完整備份時，也能先做同樣的 staging 還原檢查。

1
ARCHIVE=/absolute/path/to/openclaw-backup.tar.gz
2
openclaw backup verify "$ARCHIVE"
3
openclaw backup restore "$ARCHIVE" --target ./restored-openclaw

2026.9.9 復原前先確認 updater 與 Doctor 狀態#

9.9 的 Failed-update recovery 說明指出，受支援的 updater 可恢復相容安裝並保留本次嘗試期間寫入的資料；恢復到 9.8 後也能繼續更新。但已開始執行的舊 updater 不會獲得這些保障，macOS 與 Linux 也要等 Doctor 程序確認停止才可重新啟動。

復原時把「現在已安裝的版本」「執行這次更新的 updater」「預計恢復的版本」分開記錄。依官方 repair 指引完成後，再查 update record 與 Gateway status；若 Doctor 尚在 cleanup，或 recovery 指示尚未完成，就先停在這裡，不要平行開另一個 Gateway。應用程式可恢復，也不表示已提交的 archive／資料庫變更可逆。

Telegram 開 Control UI，要重新取得 /controlui 按鈕#

9.9 將 Mini App 入口與 session dashboard 分開：在 bot 私訊送 /controlui 開啟 Control UI；/dashboard 改屬 session dashboard。依官方遷移說明，原本的捷徑需要替換並取得新按鈕，owner 設定也要包含使用者的 numeric Telegram ID，不能把 username 或 wildcard 當成同等條件。

這段適用於原本已完成 Mini App 設定的 bot；更換指令不會代替 HTTPS 與 Tailscale 發布設定。Owner ID 要核對目前 bot account 的有效 allowFrom 或 commands.ownerAllowFrom，不能只查另一個 account 的清單。先在測試 bot 私訊取得新按鈕，確認是預期 Gateway 的 Control UI，再驗收一次訊息收發。若只有舊按鈕失效，先查入口與 owner ID；若一般訊息也失敗，分開查 channel 狀態。不要以一次入口錯誤直接重裝 Gateway，也不要為了測試把正式 owner 規則放寬。

9.9 GitHub release仍註明 Telegram integration checks 被 release owner 豁免、未執行。這份紀錄是測試範圍限制，不能證明 Telegram 已故障，也不能替自己的 Mini App 與收發驗收背書。

2026.9.8 要分開驗收更新器與訊息工作流#

9.8 官方 release notes列出 Windows 暫時檔案鎖、macOS 安裝路徑別名及更新 repair 的修復；但新修復只在新版 updater 開始執行後適用。已在舊版開始的更新不會中途換成新程式，不能以「目標版本已修」推論第一次升級一定成功。

遇到失敗時，先記錄目前安裝版本、目標版本、啟動更新的服務帳號與第一個錯誤，再對照更新排障文件：

• 9.5／9.6 出現 Assigning to rvalue 類 snapshot parse error 時，先確認 log 指名的 Plugin；官方提供單次停用該 Plugin、更新、再啟用的流程。不要把全部 Plugin 一次刪除。
• Windows 9.4 的舊資料庫 reader 仍運作時，不能強迫不相容 migration。先保留備份，讓原安裝 owner 依官方獨立 shell 流程停止舊程序、手動更新、執行新版 Doctor，再啟動與驗證；服務帳號、npm prefix、profile 與 override 都要保持一致。
• 9.8 repair 保留 Plugin allowlist 與 enabled 設定，不等於不相容 Plugin 已可正常使用。比對升級前後設定，再用該 Plugin 的實際任務驗收。

這些是依錯誤選擇的復原路徑，沒有在本文環境執行。不要為了一般升級先套用 Windows 復原操作，也不要手動改 schema 標記來假裝 migration 完成。

9.6 headless node 要先完成一次手動更新#

2026.9.7 release notes 說明：使用預設 Plugin 的 headless node，可以在閒置時啟用已準備的更新；但公開發布的 2026.9.6 節點需要先做一次：

1
openclaw update
2
openclaw node restart

請在該節點自己的安裝環境、工作結束並確認備份後執行。若是以前景模式跑 openclaw node run，應停止並重新啟動該前景程序，不能拿 service restart 代替。這些命令尚未在本次維護實際執行。

驗收時記錄節點版本、啟動方式與更新狀態，再用原本通過的節點任務確認連線和工具可用。Gateway 更新成功不能單獨證明遠端節點也完成切換。若更新仍延後，依官方排障文件檢查是否有執行中的工作、無法回報 idle 的 Plugin 或資料庫相容性限制；不要強制重啟來掩蓋延後原因。

2026.9.6 macOS app 出現啟動問題時先做什麼#

OpenClaw 官方 release page 記錄，2026.9.6 最初的 macOS app build 會在啟動時崩潰，並於 2026-09-24 09<52> UTC 換成重建、重新 notarized 的版本。若你裝過舊 build 且 app 無法開啟，依 release page 重新下載目前 DMG 安裝一次；npm package 沒有更動，所以這個 app 問題不需要靠重裝 npm CLI 處理。

先確認症狀屬於哪一層：只有 macOS app 啟動失敗時，檢查 DMG build；若 CLI 或 Gateway 升級失敗，先看 Node 版本、update status 和 service runtime，不要把兩種錯誤當成同一個原因。

2026.9.5 引入、在後續升級仍需驗收的功能#

升級前先確認 Node 與 service runtime#

目前文件查核的 OpenClaw Node 基線是 Node 24 至少 24.16.0，或 Node 26 至少 26.1.0，並且連結的 SQLite 必須符合 WAL reset 安全要求。若是系統套件自行連結 SQLite，不能只用 Node 版本字串判定相容；依 Node 官方安裝文件確認 runtime capability checks。Node 22、23、25，以及較早的 24.x／26.x build 不應直接拿來判定目前版本相容。

先記錄互動 shell 看到的版本與 Gateway 狀態：

1
node --version
2
which node
3
openclaw --version
4
openclaw update status
5
openclaw gateway status

如果 shell 使用的是 Node 26.1+，但 systemd、launchd、container 或版本管理器啟動的 Gateway 仍指向另一個 Node，升級結果可能變成「CLI 正常、service 起不來」。這時先查 service 的 PATH、映像與啟動 log，不要先重裝 OpenClaw。

保存可以回復的證據#

升級前至少保存以下資訊：

1. OpenClaw、Node、安裝方式、Gateway 啟動方式與 service owner。
2. ~/.openclaw 的受控備份。這裡可能包含 API key、OAuth、private session 與其他敏感資料，不要上傳公開 repository。
3. 啟用中的 Plugin、model primary／fallback、provider account、channel 與 agent Skills 清單。
4. 一個可以重複的 smoke test，例如讀取指定檔案、完成單次模型呼叫與傳送測試 channel 訊息。

Atomic Updates 的候選檢查只是在另一份環境驗證下一版，不是上述備份的替代品。尤其 release notes 明確提醒，回復應用程式版本不能撤銷已完成的資料庫 migration。

若要建立本機狀態備份，先停止會持續寫入資料的程序，再使用既有的加密備份流程。不要只複製 openclaw.json：發生 migration 或 session 損壞時，只有設定檔通常不足以恢復已知健康狀態。

先 status、再 dry-run，最後才 activation#

先確認目前版本與預計目標：

1
openclaw update status
2
openclaw update --dry-run

檢查 Node、channel、目標版本、Plugin 變更與預計的 service 行為後，再安排 maintenance window 執行：

1
openclaw update

執行時把以下條件寫進變更紀錄：

• 現在的版本、Node 路徑與備份位置。
• 預計會被停止或重啟的 Gateway、Plugin 與 channel。
• 停止條件：候選檢查失敗、Gateway health check 失敗、資料庫 migration 報錯或核心 smoke test 不通過。
• 回復負責人與 service owner；外部 supervisor 不能只靠 OpenClaw CLI 代替管理。

驗證 copy 成功只代表候選版本通過 OpenClaw 能檢查到的項目，不代表私有 Plugin、外部工具、channel、secrets 與自訂 service 已被你的環境驗收。

更新失敗怎麼讀#

更新結果不只看最後一行的 failed 或 success。先保留 update record、Gateway log、Node 路徑、候選驗證結果與 service 狀態，再依序查看：

1
openclaw update status
2
openclaw doctor
3
openclaw gateway status

若 release notes 指示需要 repair，再使用對應的 repair 命令；不要為了「清掉錯誤」直接反覆執行帶有確認跳過的旗標。需要 JSON 或自動化處理時，也應先確認 updater 已結束、profile 與 state/config override 一致，再依官方指引執行：

1
openclaw update repair --yes --json

Atomic Updates 的失敗處理有幾個容易誤判的邊界：

• 主要錯誤與 cleanup 錯誤分開看：後續 repair 失敗不能取代最初的 update failure。
• 恢復健康檢查未完成，不代表 rollback 完成：檢查失敗時保留的原因與 recovery commands 才是下一個線索。
• Gateway 可能維持 stopped：activation timeout、恢復未完成或外部 systemd 尚未由 owner 停止時，不要直接重新啟動多個副本。
• 保留 preserved originals：完成檢查前不要刪掉修復流程保留的檔案，否則可能失去比錯誤摘要更完整的證據。

如果問題是 Node 不支援，先修 service runtime；如果是第三方 Plugin，先在隔離環境停用並重跑；如果是設定 migration，從備份與 diff 找出具體欄位。回復的目標是恢復已知健康版本，不是強迫新版本在不相容狀態下啟動。

Plugin 可以免重啟，不代表可以免驗收#

2026.9.5 的部分 Plugin 安裝流程可以不重啟 Gateway。這對維持對話或降低 maintenance window 有幫助，但不應被解讀成「安裝後立即安全」：

1. 先確認 Plugin 來源、版本、權限、需要的 secrets 與外部連線。
2. 在 read-only workspace 執行 discovery 或 health check，記錄實際載入的版本。
3. 用最小權限任務驗證讀取、寫入、shell、browser 與外部 API 是否各自符合預期。
4. 只有確認 Plugin readiness、Gateway log 與 smoke test 都正常後，才讓它進入既有工作流。

不要因為名稱看起來官方或推薦，就自動授予 shell、browser、寫檔與外部服務權限。更新本身通過候選檢查，也不會替你的組織完成 Plugin 的權限審查。

Skills、workspace 與資料分享要拆開測試#

較早版本已把 Skills Workshop 的 ownership、Skills／Plugin discovery、雲端 workspace 重用與 public conversation 帶入更新流程。在後續升級前，仍應逐項確認：

• agent-owned Skills collection 是否完整，同名 Skill 是否因舊 workspace 複製而重複。
• discovery 找到的 Skill 或 Plugin 是否真的符合來源、版本、權限與 secrets 政策。
• private repository 的新 checkout 是否使用預期的 credentials、bind mount 與 workspace path。
• public conversation、Team Reports 或 browser session 是否意外擴大資料可見性；沒有明確分享需求時，不要只為測試點 publish。
• 舊 migration、session history 與 Doctor repair 是否完成；不要只看 UI 能否開啟就判定資料已正常。

先完成 Node、Gateway、模型、Plugin、Skills 與 channel 的基本驗收，再逐一啟用其他能力。把 runtime、資料可見性與 agent 權限混成一次大變更，會讓失敗原因難以還原。

升級後的驗收清單#

完成 activation 後，先跑：

1
node --version
2
openclaw --version
3
openclaw update status
4
openclaw gateway status
5
openclaw doctor

接著逐項驗收：

1. Runtime：互動 shell 與 service 使用同一個受支援 Node，restart 後 Gateway health 正常。
2. 更新記錄：update record、候選檢查結果與任何 Doctor warning 都可追溯。
3. 模型與帳號：primary、fallback、provider account 順序沒有被意外改寫。
4. Plugin／Skills：實際載入版本、ownership、權限與 secrets 邊界符合預期。
5. 資料與 channel：舊記憶可讀、單次模型呼叫成功、實際 channel 能收發，沒有把斷線 session 誤報為 idle。
6. 回復能力：備份可讀，負責人知道 service owner 與下一個 recovery command；不要把「目前看起來正常」當成已完成回復演練。

常見問題#