On this page
To upgrade without losing configuration, separate the plugin, core, subscription, and backup first
OpenClash upgrades most often fail when the LuCI plugin, Mihomo core, subscription configuration, and overrides all change at once. Back up first, then change only one layer. Continue only after each layer passes, so a broken page, a core that will not start, or a failed subscription update has a corresponding rollback file.
As of 2026-07-16, the official OpenClash Latest release is v0.47.116 and provides both luci-app-openclash_0.47.116_all.ipk and luci-app-openclash-0.47.116.apk.
Traditional opkg systems use IPK, while newer OpenWrt branches with the apk package manager use APK. Do not mix them merely because the extensions look similar.
Confirm over Ethernet or the local network that you can still open the router admin page when OpenClash is stopped, then inspect /overlay and /tmp. Do not directly upgrade the plugin or core for an entire remote network when no backup access path exists.
df -h /overlay /tmp
if command -v opkg >/dev/null 2>&1; then
opkg list-installed | grep -i openclash
else
apk list --installed | grep -i openclash
fi
uci show openclash.config.config_pathKeep both an in-app backup and a manual archive
The official Release notes state that plugin settings can be backed up and that an archive can be uploaded under “Configuration File Management” for restoration. First generate a backup in the interface and download it to your computer, then create a manual archive so you can confirm which files were actually saved.
Common critical locations include /etc/config/openclash, /etc/openclash/config, custom, overwrite, and core. Configurations and subscriptions contain real credentials, so do not put the archive on a public cloud drive.
BACKUP=/tmp/openclash-backup-$(date +%F-%H%M).tgz
set --
for ITEM in etc/config/openclash etc/openclash/config etc/openclash/custom etc/openclash/overwrite etc/openclash/core; do
[ -e "/$ITEM" ] && set -- "$@" "$ITEM"
done
[ "$#" -gt 0 ] || { echo 'No OpenClash files found'; exit 1; }
tar -C / -czf "$BACKUP" "$@"
ls -lh "$BACKUP"
tar -tzf "$BACKUP" | sed -n '1,40p'Upgrade only the LuCI plugin first; leave the core and subscription unchanged
After confirming that the backup lists files, update only the web plugin first. Keep using the existing core and configuration. If the page fails, the cause is limited to the LuCI package and its dependencies.
# opkg 系统
opkg install /tmp/luci-app-openclash_0.47.116_all.ipk
# apk 系统只使用对应 APK，不执行上面的 opkg 命令
apk add --force-overwrite --clean-protected --allow-untrusted /tmp/luci-app-openclash-0.47.116.apkAfter installation, refresh LuCI and inspect the OpenClash page, configuration list, and version-update page. A blank page, dependency error, or missing menu points to the plugin and system packages; do not proceed to replace the Mihomo core or update subscriptions.
Once the page works, update the clash_meta core
Official OpenClash instructions require checking the core build version on the version-update page first. For a manual installation, extract the core to /etc/openclash/core/, name it clash_meta, match it to the router's CPU architecture, and grant execute permission.
Keep a copy of the old core and load the same existing configuration after the update. Exec format error usually means the architecture is wrong; Permission denied points to execute permission; only a YAML parsing failure sends you back to the configuration fields.
cp -a /etc/openclash/core/clash_meta /etc/openclash/core/clash_meta.before-upgrade
chmod 0755 /etc/openclash/core/clash_meta
/etc/openclash/core/clash_meta -vAfter both plugin and core are stable, update the subscription manually once
During upgrade verification, continue using the existing configuration and nodes so any failure cannot come from the subscription. Once the page, core version, DNS, and rules all work, update only one frequently used subscription under “Configuration Subscription,” then record the update time, node count, and first error. Do not change the subscription address, conversion template, and overrides on upgrade day.
A subscription URL or token is generally stored in OpenClash configuration and UCI settings, making backup files sensitive. If a restored list contains names but will not update, first check that the URL is complete, the system time is correct, and whether the response is 401/403; do not overwrite the plugin package again.
Update returns 401 / 403
The subscription credentials or service permissions are invalid; keep the old configuration running and obtain a legitimate URL again.
Download succeeds, but YAML parsing fails
Compare the configuration before and after the update and the fields supported by the current Mihomo version; do not roll back the LuCI plugin.
Nodes update, but custom rules disappear
Restore custom/overwrite and verify the override load order; do not mistake a cache for a backup.
Choose only one recovery method: interface import or complete archive
Under normal conditions, prefer a backup exported by OpenClash itself. Restore original paths over SSH only if the interface no longer works and you have verified the manual archive. Do not combine both methods in one recovery.
Recovery order
Stop OpenClash
Prevent the process from writing configuration and cache files while extraction is in progress.
Import the official backup through Configuration File Management first
This is the safest entry point for most users; inspect configuration paths after import.
Use SSH only for a manual archive
Save the current directories elsewhere before extracting the archive to the original paths.
Restore permissions and start
Confirm that clash_meta is executable, commit UCI changes, then start OpenClash.
Connect one device first
Restore the entire household only after direct access, proxying, DNS, and router administration all work.
BACKUP='/tmp/openclash-backup-YYYY-MM-DD-HHMM.tgz'
tar -tzf "$BACKUP" | sed -n '1,80p'
/etc/init.d/openclash stop
cp -a /etc/openclash /etc/openclash.failed-$(date +%F-%H%M)
tar -C / -xzf "$BACKUP"
chmod 0755 /etc/openclash/core/clash_meta
uci commit openclash
/etc/init.d/openclash restartStop at whichever layer fails first
An upgrade is complete only when the router page, core, configuration, and client devices all work again—not merely when the version number changes. If any layer reports an error, return to that step and do not update the next layer.
LuCI page is blank or returns 404
Roll back the plugin package, repair dependencies, or clear the browser cache; do not change the core or subscription.
clash_meta cannot execute
Restore the before-upgrade file and check CPU architecture and permissions.
The core starts, but DNS fails on every client
Switch back to the old core or configuration, then inspect DNS interception and firewall changes.
Custom rules or overrides disappear
Restore from custom/overwrite or the official backup; do not overwrite all of OpenWrt.
Only the TV or game console has problems
Reconnect that device and clear its old DNS lease first; do not continue upgrading other components.
Before restoring the whole household
- The LuCI page opens, and the plugin version matches the installed package
- clash_meta -v runs, and the startup log contains no architecture, permission, or parsing errors
- The usual subscription updates, and custom rules and overrides remain intact
- Use one computer to test direct access, proxying, DNS, and the router admin page separately
- Only then let phones, TVs, and game consoles renew DHCP and DNS