本文目录
先看日志停在哪一阶段，不要把两种失败混在一起
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 后，路由器仍有明确的直连与管理回退路径