On this page
The router’s update button handles downloading, checking, and installing in sequence, but a failure message may show only the last line. The installer’s original output tells you whether installation actually began and helps you avoid repeatedly overwriting packages while the router is still manageable.
After downloading, did the test or installation fail?
Find where the OpenClash APK update stopped in the logs: download, pre-update testing, or actual installation. Here, APK is the router package format. “Download successful” only confirms that /tmp/openclash.apk was written to the router; it does not prove that testing or installation passed.
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 | Other errors still occur during the simulated installation | Keep the complete apk output and check system package state first |
| The pre-update test passes, then package installation fails | The pre-installation check passed, but the actual installation failed | 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 testUse apk-tools to simulate installation and check the arguments and installation operations
- 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.
Check the APK package format and keep local management access
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 for APK systems, while traditional OpenWrt firmware uses opkg and IPK. These package managers and formats are not interchangeable. The commands below apply only to devices whose logs explicitly show 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
The allow-downgrade parameter error and simulated checks
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 this argument error, first simulate a check of the system packages rather than installing the official APK. Alpine documentation states that --simulate does not commit database changes. Save any dependency, world constraint, or other errors; do not simply remove --simulate from fix and run it.
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.
Simulate the installation with the official command, then install once if the check passes
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.
If the test passes but installation still fails, stop clicking repeatedly in LuCI. Run the actual command below over SSH and save the full apk output to distinguish dependency, signature, disk-space, lock, and I/O problems.
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.
How do you recover if APK installation fails or the new plugin malfunctions?
If manual installation succeeds but LuCI will not open, OpenClash will not start, or existing overrides are missing, stop OpenClash first. Restore local management access to the router without going through the plugin, then restore the configuration from the backup exported before the update. Restore the plugin package, Mihomo core, subscription, and overrides separately; one firmware rollback cannot replace these steps.
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 |
Check the LuCI plugin, proxy service, and device connectivity separately
Verify plugin installation and proxy service recovery separately. Confirm the installed version in LuCI or apk info, then start OpenClash and check that the core architecture, configuration, subscription, and overrides still match. Only after the service is stable should you make new DNS and page requests from a LAN device.
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