本文目錄
先看日誌停在哪一階段，不要把兩種失敗混在一起
OpenClash 的 APK 更新會依序下載安裝套件、執行更新前測試，再進入實際安裝。日誌裡出現「下載成功」只說明 /tmp/openclash.apk 已經寫入路由器，不代表後兩步都會成功。
OpenClash 官方 issue #5256 自 2026 年 7 月 28 日起同時記錄了兩類現象：一種在「更新前測試」就因 unrecognized option 'allow-downgrade' 停止；另一種明確顯示「更新前測試透過」，卻在隨後「軟體套件安裝失敗」。
截至 2026 年 8 月 6 日，該 issue 仍為 Open，專案尚未給出適用於所有裝置的統一根因。
用日誌決定下一步
| 最後一組關鍵日誌 | 目前能確認什麼 | 下一步 |
|---|---|---|
| 更新前測試失敗，並出現 unrecognized option 'allow-downgrade' | 目前 apk-tools 不接受該參數，尚未進入實際安裝 | 核對 APK 來源，再使用官方 Release 中不帶該參數的寫法 |
| 更新前測試失敗，但沒有參數錯誤 | 模擬事務還存在其他錯誤 | 保留完整 apk 輸出，先檢查系統套件狀態 |
| 更新前測試透過，隨後軟體套件安裝失敗 | 前置檢查已透過，失敗發生在實際事務 | 停止反覆按一下，改由 SSH 取得原始安裝錯誤 |
| 下載失敗，或 /tmp/openclash.apk 不存在 | 還沒有完整安裝套件 | 先處理下載、來源或儲存問題 |
- 下載安裝套件把 openclash.apk 寫入 /tmp
- 更新前測試讓 apk-tools 模擬檢查參數與事務
- 實際安裝把透過檢查的軟體套件寫入系統
- 服務驗證重啟外掛程式並檢查設定、核心與網路
「更新前測試失敗」和「測試透過後安裝失敗」發生在不同階段；先讀最後一條 apk 錯誤，再決定是否需要手動安裝。
先備份，再確認這台路由器確實使用 APK
更新 LuCI 外掛程式前，先在 OpenClash 的設定管理頁面匯出目前備份，並確認即使 OpenClash 停止，也能透過區域網路或有線 SSH 進入路由器。訂閱、覆寫和自訂規則可能含有敏感連結，備份只能儲存在可信位置。
OpenClash v0.47.133 的官方 Release 為 APK 系統使用 apk 和 openclash.apk，傳統 OpenWrt 韌體則使用 opkg 與 IPK。兩套套件管理員和安裝套件格式不能交叉；本文只適用於日誌明確出現 apk 的裝置。
command -v apk
apk --version
apk info luci-app-openclash 2>/dev/null
df -h /overlay /tmp
ls -lh /tmp/openclash.apk手動處理前必須具備
- 已經匯出 OpenClash 設定，或確認存在可恢復備份
- 可從區域網路或有線 SSH 登入路由器
- 日誌和 command -v 結果確認使用 APK，而不是 IPK 或 opkg
- /tmp/openclash.apk 存在，且檔案大小不是 0
- 已經記錄目前 OpenClash、韌體與 apk-tools 版本
更新前測試失敗，先檢查參數和軟體套件狀態
若完整錯誤是 unrecognized option 'allow-downgrade'，含義很窄：目前 apk-tools 無法解析該選項。它不等於儲存已滿、安裝套件損壞，也不等於必須降級 OpenWrt。先查看本機幫助資訊，確認該參數是否存在。
apk add --help 2>&1 | grep -- '--allow-downgrade' || echo '当前 apk-tools 不支持 allow-downgrade'若測試失敗但沒有這條參數錯誤，可執行一次官方 APK 的模擬修復檢查。Alpine 文件說明 --simulate 不會提交資料庫變更；輸出出現依賴、world 約束或其他錯誤時，應先保留結果，不要把 fix 去掉 --simulate 後直接執行。
apk fix --simulate只報告 allow-downgrade 不受支援
進入下一節，使用不帶該參數的官方安裝寫法。
apk fix --simulate 回傳 OK
系統套件狀態未在這次模擬中暴露錯誤，繼續取得實際安裝輸出。
出現 breaks: world、依賴衝突或缺失包
停止手動安裝，核對第三方軟體套件來源和不匹配軟體套件；不要使用 force-broken-world。
空間或檔案檢查異常
先透過韌體自己的儲存管理方式處理，並保留設定備份，不盲目刪除 /overlay 內容。
只執行一次與官方 Release 一致的手動安裝
如果日誌明確因 allow-downgrade 不受支援而停止，OpenClash v0.47.133 官方 Release 給出的 APK 安裝命令並不包含該選項。確認備份、管理通道和 /tmp/openclash.apk 來源後，可先用同一組參數執行模擬安裝；模擬透過後，再去掉 --simulate 實際安裝一次。
第二類情況是日誌已經寫明「更新前測試透過」，卻在實際安裝階段失敗。此時同樣不要繼續按一下 LuCI 更新；在 SSH 中執行下面的實際命令，目的是讓 apk 把依賴、簽名、空間、鎖定或 I/O 等實際錯誤完整輸出。不要因為 issue 評論提到某個原因，就預先改動系統。
apk add --simulate --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apkapk add --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apk命令完成且回傳成功
重新整理 LuCI 並核對外掛程式版本，再按最終清單驗證服務。
仍提示 unrecognized option
儲存完整命令與輸出，確認實際執行的 apk 路徑和版本，不繼續猜參數。
出現 UNTRUSTED signature，且檔案並非官方來源
立即停止，不再增加強制參數，重新從官方 Release 取得安裝套件。
出現依賴、world、空間、鎖定或只讀檔案系統錯誤
保留原始輸出並按該錯誤處理；不要重複執行更多強制變體。
安裝無效時退回上一個可用狀態
手動安裝成功，卻出現 LuCI 無法開啟、OpenClash 無法啟動或原有覆寫缺失時，先停止 OpenClash，讓路由器恢復不經過外掛程式的本機管理路徑，再從更新前匯出的備份恢復設定。外掛程式包、Mihomo 核心、訂閱和覆寫屬於不同層，不能用一次韌體還原代替逐層恢復。
如果 apk 命令本身失敗，保留 /tmp/openclash.apk、終端輸出和設定備份，不要反覆執行帶更多 force 參數的變體。需要退回舊版本時，優先使用目前韌體軟體套件來源中與系統匹配的包或已確認可用的官方包；沒有可驗證的降級路徑，就保持目前可管理狀態並向官方 issue 提交脫敏日誌。
按實際影響範圍還原
| 結果 | 保留什麼 | 還原動作 |
|---|---|---|
| APK 命令失敗，舊頁面仍可用 | 原始 apk 輸出與目前設定 | 停止重試，恢復原服務狀態 |
| 安裝成功，但頁面或服務異常 | 更新前的 OpenClash 備份 | 停止服務後恢復設定，再核對核心架構 |
| 更新後全屋裝置無法存取 | 路由器本機管理入口 | 暫時停用 OpenClash，先確認 OpenWrt 直連恢復 |
| 區域網路也無法管理路由器 | 原有有線或 failsafe 預案 | 先恢復管理通道，不在不可觀察狀態下繼續升級 |
外掛程式裝上以後，再分別驗證服務和全屋網路
最後把「外掛程式安裝成功」和「代理服務恢復」拆開驗證。先在 LuCI 或 apk info 中確認已安裝版本，再啟動 OpenClash，檢查核心架構、設定、訂閱和覆寫是否仍然匹配。只有服務穩定後，才從一台 LAN 終端發起新的 DNS 與網頁請求。
外掛程式頁面正常而分流仍異常，應轉去檢查核心、訂閱、DNS 與路由規則，不再重複 apk 安裝。反過來，網路可用但 LuCI 版本沒有變化，也應回到包安裝日誌，不憑頁面快取判斷升級完成。
完成更新的驗證清單
- apk info 或 LuCI 顯示的 OpenClash 版本與本次目標一致
- OpenClash 頁面能開啟，設定、覆寫和訂閱仍可見
- Mihomo 核心架構與路由器平台一致，啟動日誌沒有新錯誤
- 一台 LAN 終端能解析新網域並開啟普通網頁
- 連線記錄顯示測試請求命中預期規則和策略
- 停用 OpenClash 後，路由器仍有明確的直連與管理還原路徑