OpenClash on OpenWrt: a LuCI manager for Mihomo whose install scripts need a second look

A LuCI front end that manages Mihomo rather than a proxy engine of its own

OpenClash is a LuCI plugin for OpenWrt. It does not implement proxy protocols itself; it manages the Mihomo kernel, formerly called Clash Meta and maintained by MetaCubeX, and gives it a web interface inside the router's admin pages. Through Mihomo it handles Shadowsocks, ShadowsocksR, VMess, VLESS, Trojan, Snell, TUIC and Hysteria, and it splits traffic by rules into a transparent proxy for the whole network. After installation it appears under Services, then OpenClash, where you import a subscription or upload a config file and start the service. The repository is small at the top level: luci-app-openclash/ holds the package, with img/, an announcement file and .github/ beside it. The code is MIT licensed and GitHub reports HTML as the main language, which reflects how much of the plugin is LuCI page markup. The default branch is master and it received a push on 2026-11-02.

Two kernels, four dashboards and a code base inherited from Luci For Clash

The plugin ships with two kernel options, Mihomo (Meta) and a Smart kernel, and it can update and switch between them online. On top of the kernel it bundles four control panels: metacubexd from MetaCubeX is the default, with zashboard, Yacd-meta (based on yacd) and Razord-meta as alternatives. A CodeMirror editor is built in for editing configuration files in the browser. The project credits Luci For Clash by frainzy1477 as the code base it grew from, so OpenClash is a continuation of an earlier LuCI Clash client rather than a fresh design. Configuration management covers several config files with one-click switching, online editing, backup and restore, and Age encryption of configs. Access control is handled through black and white lists plus custom firewall rules. For streaming services such as Netflix, Disney+ and HBO it can pick a working route automatically, using lmc999's RegionRestrictionCheck for the unlock detection.

redir-host, fake-ip and TUN modes split across iptables and nftables

Running modes are redir-host and fake-ip, a mixed mode, and TUN mode, and the plugin works with both iptables and nftables. Which firewall your OpenWrt build uses decides almost everything about installation. The iptables path needs iptables, kmod-ipt-nat, iptables-mod-tproxy and iptables-mod-extra. The nftables path, which the project ties to Firewall4, needs kmod-nft-tproxy instead. Some features have their own optional modules: kmod-tun is needed for TUN mode, ip6tables-mod-nat for IPv6, and kmod-inet-diag for PROCESS-NAME rules. The consequence is that IPv6 users on the iptables path have to add ip6tables-mod-nat themselves, since none of the install commands include it, and anyone who wants TUN mode must make sure kmod-tun is available for their target. Choosing the wrong install block for your firewall leaves you with a plugin that loads in LuCI but lacks the kernel modules its proxy modes depend on.

The iptables install command downloads the package but never installs it

Two command-line recipes are given, one per firewall. Both fetch the latest release metadata from the GitHub API, pick the asset whose name ends in .ipk with jsonfilter, and save it to /tmp/openclash.ipk. The iptables recipe ends here:

[ -f "/tmp/openclash_version" ] && download_url=$(cat /tmp/openclash_version | jsonfilter -e '@.assets[*].browser_download_url' | grep '\.ipk$') && curl -L --retry 2 "$download_url" -o /tmp/openclash.ipk || echo "OpenClash last version get failed"
[ -f "/tmp/openclash.ipk" ]

The final line only tests whether the file exists. Nothing installs it, so after pasting the block you still have to run opkg install on /tmp/openclash.ipk yourself. The nftables recipe goes one step further but ends on a dangling operator:

[ -f "/tmp/openclash.ipk" ] && opkg install /tmp/openclash.ipk ||

Pasted as is, that trailing || leaves the shell waiting for a continuation instead of finishing. Both recipes also filter for .ipk only and run opkg update, so neither covers the apk package (luci-app-openclash-*.apk) that releases now carry for apk-based systems. Users on those systems are left with the web upload route.

The dependency table and the opkg package lists disagree

The dependency table and the opkg commands are not the same list. The table lists kmod-ipt-nat as an iptables firewall requirement, but the iptables opkg install line does not include it. The table also puts ipset under networking requirements, and the nftables opkg line leaves ipset out, which may be intentional for Firewall4 but is not explained. The base requirements are luci, luci-base and luci-compat with LuCI 19.07 or newer, and the runtime set is bash, curl, ca-bundle, ruby and ruby-yaml, plus dnsmasq-full, ip-full and unzip. The practical effect is that following the command alone can leave a module missing, and the failure shows up later as a proxy mode that will not start rather than as an install error. Treat the table as the reference and check each entry with opkg before starting the service. Note too that a Ruby runtime and its YAML library are installed onto the router, which costs flash space on small devices.

First start downloads the core, so the router needs a route out beforehand

Installing the package does not install a working proxy. The project warns that first use requires downloading the kernel and asks you to confirm your network environment in advance. That creates an ordering problem on networks where the download sources are hard to reach without a proxy: the router has to fetch Mihomo before OpenClash can provide the very route that might be needed to fetch it. Plan for that before you replace an existing setup, for example by keeping the old path working until the core is in place. The same applies to the data OpenClash relies on. GeoIP and GeoSite data come from Loyalsoldier's v2ray-rules-dat and MetaCubeX's meta-rules-dat, the China IP list from alecthw's mmdb_china_ip_list, and carrier IP ranges from gaoyifan's china-operator-ip. Public IP checks use ip.skk.moe. Each of these is an outside download, and rules that depend on them stay incomplete until they arrive.

The source build starts from a 15.05.1 SDK while the plugin wants LuCI 19.07

Building from source is shown against the OpenWrt Chaos Calmer 15.05.1 SDK for ar71xx, fetched with curl using -k, which skips TLS certificate checks on that download. The repository is cloned with a sparse checkout so only the package directory comes down:

git config core.sparsecheckout true
echo "luci-app-openclash" >> .git/info/sparse-checkout
git pull --depth 1 origin master

After that, make menuconfig is used to select LuCI, then Applications, then luci-app-openclash. You can also copy the luci-app-openclash folder into the package directory of another OpenWrt tree and build it with the firmware. The friction is that the same project declares LuCI 19.07 or newer as a base requirement, while the example SDK is several OpenWrt generations older. Take the commands as a pattern for the sparse checkout and menuconfig steps, and swap in the SDK that matches your target and release instead of the one in the example.

Subscriptions, override YAML and a user guide kept on the dev branch

OpenClash can hold several subscriptions at once, set a custom User-Agent and request headers per subscription, and run them through Subconverter (tindy2013/subconverter) for online conversion. Online conversion means the subscription link is handed to a conversion service, so check which backend handles it before using a subscription that carries credentials. Conversion rule templates from ACL4SSR and Aethersailor's Custom_OpenClash_Rules are credited. For edits that should survive a subscription refresh, the plugin offers modular override YAML, which layers your changes on top of the downloaded config. The user manual link points to a SKILL.md file under .github/skills/openclash-user-guide on the dev branch, while builds and installs pull from master, so the guide can describe behaviour that has not reached a release yet. Releases are frequent: v0.47.133 on 2026-07-18, v0.47.156 on 2026-08-10 and v0.48.002 on 2026-10-12. Support discussion happens in a Telegram group.

Editorial conclusion

OpenClash fits OpenWrt users on LuCI 19.07 or newer who want Mihomo with subscription management, fake-ip or TUN modes and a choice of dashboards, all from the router's web interface. It is a poor fit for routers with little flash or no way to fetch the kernel on first start, and for anyone who expects the copy-paste install commands to finish the job. Before installing, check your firewall stack (iptables or Firewall4), compare the opkg command against the full dependency table, and confirm the router can download the core.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. vernesong/OpenClash on GitHub