On this page
First identify the stage where the log stops; do not mix the two failures
An OpenClash APK update downloads the package, runs a pre-update test, and then performs the actual installation. “Download successful” in the log means only that /tmp/openclash.apk was written to the router; it does not prove that the next two steps will succeed.
OpenClash official issue #5256 has documented two behaviors since 7/28/2026: one stops during the pre-update test with unrecognized option 'allow-downgrade'; the other explicitly says the pre-update test passed, then reports package installation failed.
As of 8/6/2026, the issue remained Open, and the project had not identified one root cause that applies to every device.
Use the log to choose the next step
| Final group of important log entries | What can currently be confirmed | Next step |
|---|---|---|
| The pre-update test fails with unrecognized option 'allow-downgrade' | The current apk-tools does not accept that argument, so actual installation has not started | Verify the APK source, then use the form from the official Release without that argument |
| The pre-update test fails without an argument error | The simulated transaction has another error | Keep the complete apk output and check system package state first |
| The pre-update test passes, then package installation fails | The preliminary check passed; the failure occurs in the actual transaction | Stop clicking repeatedly and use SSH to capture the raw installation error |
| The download fails, or /tmp/openclash.apk does not exist | There is not yet a complete installation package | Address the download, source, or storage problem first |
- Download the installation packageWrite openclash.apk to /tmp
- Pre-update testHave apk-tools simulate checking the arguments and transaction
- Actual installationWrite the validated package to the system
- Service validationRestart the plugin and check the configuration, core, and network
“Pre-update test failed” and “installation failed after the test passed” occur at different stages. Read the last apk error first, then decide whether a manual installation is needed.
Back up first, then confirm that this router actually uses APK
Before updating the LuCI plugin, export a current backup from OpenClash Configuration Management and confirm that you can still reach the router over the LAN or wired SSH if OpenClash stops. Subscriptions, overrides, and custom rules may contain sensitive links, so store the backup only in a trusted location.
The official OpenClash v0.47.133 Release uses apk and openclash.apk on APK systems, while traditional OpenWrt firmware uses opkg and IPK. Package managers and package formats cannot be mixed. This article applies only to devices whose logs explicitly contain apk.
command -v apk
apk --version
apk info luci-app-openclash 2>/dev/null
df -h /overlay /tmp
ls -lh /tmp/openclash.apkRequirements before manual handling
- The OpenClash configuration has been exported, or a recoverable backup is confirmed
- The router can be accessed over the LAN or wired SSH
- Logs and command -v results confirm that the system uses APK, not IPK or opkg
- /tmp/openclash.apk exists and its file size is not 0
- The current OpenClash, firmware, and apk-tools versions have been recorded
If the pre-update test fails, check the arguments and package state first
If the complete error is unrecognized option 'allow-downgrade', its meaning is narrow: the current apk-tools cannot parse that option. It does not mean storage is full, the package is corrupted, or OpenWrt must be downgraded. Inspect the local help output first to see whether the option exists.
apk add --help 2>&1 | grep -- '--allow-downgrade' || echo '当前 apk-tools 不支持 allow-downgrade'If the test fails without that argument error, run one simulated repair check against the official APK. Alpine documentation states that --simulate does not commit database changes. If the output shows a dependency, world constraint, or another error, keep the result; do not remove --simulate from fix and run it directly.
apk fix --simulateOnly allow-downgrade is reported as unsupported
Proceed to the next section and use the official installation form without that option.
apk fix --simulate returns OK
The package state exposed no errors in this simulation; continue to capture the actual installation output.
breaks: world, a dependency conflict, or a missing package appears
Stop the manual installation and check third-party repositories and mismatched packages. Do not use force-broken-world.
A storage or file check is abnormal
Address it using the firmware's own storage-management method and keep a configuration backup. Do not blindly delete /overlay contents.
Run one manual installation matching the official Release
If the log clearly stops because allow-downgrade is unsupported, the APK installation command in the official OpenClash v0.47.133 Release does not include that option. After confirming the backup, management path, and source of /tmp/openclash.apk, simulate the installation with the same arguments. If the simulation passes, remove --simulate and perform the installation once.
The second case is a log that explicitly says the pre-update test passed but fails during the actual installation. Do not keep clicking Update in LuCI. Run the actual command below over SSH so apk prints the complete dependency, signature, storage, lock, or I/O error. Do not change the system in advance based on a cause mentioned in an issue comment.
apk add --simulate --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apkapk add --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apkThe command completes successfully
Refresh LuCI and verify the plugin version, then validate the service with the final checklist.
unrecognized option still appears
Save the complete command and output, confirm the actual apk path and version, and stop guessing arguments.
UNTRUSTED signature appears, and the file is not from an official source
Stop immediately. Do not add more force options; download the package again from the official Release.
A dependency, world, storage, lock, or read-only filesystem error appears
Keep the raw output and address that specific error. Do not run more force variants.
If installation does not work, return to the previous working state
If manual installation succeeds but LuCI will not open, OpenClash will not start, or existing overrides disappear, stop OpenClash first and restore the router's local management path without the plugin. Then restore the configuration from the pre-update backup. The plugin package, Mihomo core, subscription, and overrides are separate layers; do not replace layer-by-layer recovery with one firmware rollback.
If the apk command itself fails, keep /tmp/openclash.apk, terminal output, and the configuration backup. Do not repeatedly run variants with more force options. To return to an older release, prefer a package from the current firmware repository that matches the system or an official package already confirmed to work. If there is no verifiable downgrade path, keep the current manageable state and submit redacted logs to the official issue.
Roll back according to the actual impact
| Result | What to preserve | Rollback action |
|---|---|---|
| The APK command fails, but the old page still works | The raw apk output and current configuration | Stop retrying and restore the original service state |
| Installation succeeds, but the page or service is abnormal | The pre-update OpenClash backup | Stop the service, restore the configuration, then verify the core architecture |
| Every device in the home loses access after updating | The router's local management path | Disable OpenClash temporarily and confirm that direct OpenWrt connectivity returns |
| The router cannot be managed even from the LAN | The existing wired or failsafe plan | Restore management access first; do not continue upgrading without visibility |
After the plugin installs, validate the service and whole-home network separately
Finally, validate “plugin installed” separately from “proxy service restored.” First confirm the installed release in LuCI or apk info, then start OpenClash and check whether the core architecture, configuration, subscription, and overrides still match. Only after the service is stable should one LAN endpoint make a new DNS query and webpage request.
If the plugin page works but routing remains broken, inspect the core, subscription, DNS, and routing rules instead of reinstalling with apk again. Conversely, if networking works but the LuCI version has not changed, return to the package installation log rather than relying on a cached page.
Update-completion checklist
- apk info or LuCI shows the intended OpenClash version
- The OpenClash page opens, and configurations, overrides, and subscriptions remain visible
- The Mihomo core architecture matches the router platform, with no new startup errors
- One LAN endpoint can resolve a new domain and open an ordinary webpage
- Connection records show the test request matching the expected rule and policy
- After OpenClash is disabled, the router still has a clear path for direct connectivity and management recovery