Installation and Migration · Clash Technical Blog

How to Upgrade OpenClash Without Losing Configuration: Plugins, Cores, Subscriptions, Backup, and Restore

Back up the OpenClash plugin, core, configuration, and overrides separately, then upgrade one layer at a time and stop at the first failure to avoid a home-wide outage.

Read the articleBack to blog
  • OpenClash
  • OpenWrt
  • Upgrade
  • Backup and Restore
On this page
Published
Updated
Estimated reading time
About 9 minutes

Before updating a router’s proxy plugin, consider not only whether custom rules will survive but also whether you can still reach its management page and find a usable backup if the update fails. Handle the web plugin, proxy core, and subscription separately. Verify recovery on one device before reconnecting the others, so an upgrade does not turn into troubleshooting the whole household.

Before upgrading OpenClash, check the package format, space and backup router access

LuCI is the router's web administration interface, and Mihomo is the core that handles proxy connections. When upgrading OpenClash, verify the web plugin, core and subscription configuration separately. Do not replace them and the override settings together. Save backups for each so you can restore the part that fails.

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.

Space and current version; compatible with both opkg and apk systems
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_path

Keep 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.

Create a manual backup over SSH, including only directories that actually exist
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'

After updating the LuCI plugin, the page and original configuration list should still open

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.

Run only the installation command for your router’s package manager below: IPK for an opkg system, APK for an apk system. Confirm that the file comes from the verified project release page, and do not paste and run both commands together.

Replace the package name with the file you actually downloaded
# 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.apk

After 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.

Match clash_meta to the CPU architecture and retain the old 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.

The first line below backs up the old core; the next two check the replacement. Do not run the whole block continuously. Confirm that the backup succeeded, then put the new file of the verified architecture in place. Run chmod and the version command only after replacing the file. Stop if any step fails.

Use the first line to back up before replacement; use the remaining lines to check after replacement
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 -v

Update manually in “Configuration Subscription” and check nodes and custom rules

During upgrade verification, keep using the existing configuration and nodes while checking that neither the plugin nor the core is causing problems. 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

  1. Stop OpenClash

    Prevent the process from writing configuration and cache files while extraction is in progress.

  2. Import the official backup through Configuration File Management first

    This is the safest entry point for most users; inspect configuration paths after import.

  3. Use SSH only for a manual archive

    Save the current directories elsewhere before extracting the archive to the original paths.

  4. Restore permissions and start

    Confirm that clash_meta is executable, commit UCI changes, then start OpenClash.

  5. Connect one device first

    Restore the entire household only after direct access, proxying, DNS, and router administration all work.

Manual archive recovery example; replace the BACKUP path with the real file first
BACKUP='/tmp/openclash-backup-YYYY-MM-DD-HHMM.tgz'
tar -tzf "$BACKUP" &&
/etc/init.d/openclash stop &&
cp -a /etc/openclash /etc/openclash.failed-$(date +%F-%H%M) &&
cp -a /etc/config/openclash /etc/config/openclash.failed-$(date +%F-%H%M) &&
tar -C / -xzf "$BACKUP" &&
chmod 0755 /etc/openclash/core/clash_meta &&
uci commit openclash &&
/etc/init.d/openclash restart

These commands are joined with &&, so a failed command stops the remaining commands. Check the failed step before continuing. If some files have already been extracted, do not restart the service until you have checked that the configuration and core are intact; then decide whether to continue restoring or leave the service stopped.

How to recover when the page, core, DNS or an individual device fails

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, renew its DHCP settings, and clear stale DNS cache before changing any other component.

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

References