OpenWrt-nikki: Mihomo transparent proxy as a LuCI app on OpenWrt 24.10

What Nikki adds on top of Mihomo on OpenWrt

Mihomo is a proxy core. On a router it needs three things around it before it is useful: a profile that survives updates, firewall rules that capture traffic without asking each client to configure a proxy, and a way to restart the core when something goes wrong. Nikki is the packaging that supplies those three. The README describes the project as "Transparent Proxy with Mihomo on OpenWrt" and lists the feature set as transparent proxy in Redirect, TPROXY or TUN mode over IPv4 and/or IPv6, access control, profile mixin, a profile editor and scheduled restart. The audience is the person who already runs OpenWrt as a gateway and wants per-device routing decisions made on the router rather than on each laptop.

The repository is split into three package directories at the top level: nikki/ for the core service, luci-app-nikki/ for the web interface, and two directories holding the Mihomo binaries, mihomo-alpha/ and mihomo-meta/. That layout matters when you read the install instructions, because the feed ships the core and the interface as separate packages and you can install either without the other. The primary language of the repository is JavaScript, which is the LuCI side, not the proxy core.

The five-step run sequence and where nftables enters

The README gives the mechanism as an ordered list: mixin and update the profile, run mihomo, set the scheduled restart, set ip rule and route, then generate nftables and apply it. That order is not decoration. The profile is rewritten before the core starts, so a subscription refresh and a local override are merged into one file the core reads at launch. The routing and firewall stages come last because they depend on which mode was configured.

That last point is the one the README flags explicitly: "Note that the steps above may change base on config." In Redirect mode the traffic is caught by a nat table rule; in TPROXY mode it needs the tproxy and socket kernel modules plus policy routing so the marked packets reach the local listener; in TUN mode a dummy interface carries the traffic instead. Those are three different firewall shapes produced by one package, and the dependency list reflects it, naming kmod-nft-tproxy, kmod-nft-socket, kmod-tun and kmod-dummy as required packages rather than optional extras. If you are planning a minimal build, that list is the real footprint, not the LuCI app.

The dependency set also includes yq, curl and ca-bundle. yq is there because profile mixing edits YAML, and curl with the CA bundle is there because profiles are fetched over TLS. Neither is present on a stock OpenWrt image, so the package pulls them in.

Installing OpenWrt-nikki from the feed with opkg or apk

The recommended path is the feed, and the README says the feed step only needs to be run once. It pipes a script from the repository into ash:

wget -O - https://github.com/nikkinikki-org/OpenWrt-nikki/raw/refs/heads/main/feed.sh | ash

After that, install the packages. The README gives both package managers because OpenWrt 24.10 sits on the boundary between them. Use opkg on images that still ship it, and apk on images that have moved to apk:

opkg install nikki
opkg install luci-app-nikki
opkg install luci-i18n-nikki-zh-cn

The same three packages under apk are apk add nikki, apk add luci-app-nikki and apk add luci-i18n-nikki-zh-cn. The README notes you can install from the shell or from the Software menu in LuCI, and the third package is the Simplified Chinese translation, so drop it if you do not want it. Once the LuCI package is present, the interface appears in the LuCI menu and is where the profile editor, the mixin and the restart schedule are configured. The README does not walk through the interface; it points to the project wiki for usage.

If you would rather not add a feed, the alternative is the release installer, which is a single script: wget -O - https://github.com/nikkinikki-org/OpenWrt-nikki/raw/refs/heads/main/install.sh | ash. To remove the packages and reset, the README gives uninstall.sh, fetched and piped the same way. That script is the documented rollback.

Building the package yourself instead of trusting the feed

The README documents a source build, which is the path for anyone who already builds their own OpenWrt image and does not want a third-party feed in the loop. It adds a feed line to feeds.conf.default, updates and installs the feeds, then compiles only the LuCI app:

echo "src-git nikki https://github.com/nikkinikki-org/OpenWrt-nikki.git;main" >> "feeds.conf.default"
./scripts/feeds update -a
./scripts/feeds install -a
make package/luci-app-nikki/compile

The README states the resulting package files land under bin/packages/your_architecture/nikki. Note what the build command targets: luci-app-nikki, the interface. The core package is in the same feed and is selected the same way if you want it in the image. Building from source is also the only way to pin the Mihomo binary yourself, since the repository carries mihomo-alpha/ and mihomo-meta/ as separate top-level directories rather than as a single vendored core.

Where Nikki is the wrong tool, and what OpenClash does differently

The prerequisites are hard limits, not suggestions. OpenWrt 24.10 or newer, Linux kernel 5.13 or newer, and firewall4. A router on an older release with firewall3 cannot run this package as shipped, and the README offers no compatibility path. That excludes a large installed base of older consumer routers, and it is the first thing to check before anything else.

The obvious comparison is OpenClash, which appears alongside Nikki in the search terms people use. The difference in approach is the firewall layer. OpenClash is built around the older iptables and nftables handling on OpenWrt and has a long history of working across releases that predate firewall4; Nikki is written for firewall4 and generates nftables rules rather than maintaining a dual stack. If you are on an older image, that single design decision decides the choice for you. Homeproxy and sing-box based packages are the other direction people look, and they are built on a different core entirely, so profiles and rule sets do not carry across.

The second limitation is documentation depth. The README lists the profile editor and the mixin as features and then hands the reader to the wiki. It does not describe the mixin merge semantics, what happens when a subscription refresh fails mid-write, or how a partially applied nftables ruleset is recovered. Those are the questions that decide whether a router survives an unattended update, and the README is silent on all of them. Treat the wiki as required reading, not optional.

Third, the dependency list is not small. curl, yq, ca-bundle and five kernel modules have to fit alongside the Mihomo binary on the router. On a device with tight flash, the LuCI app is not the constraint; the modules and the binary are.

Maintenance, licence and what upgrading costs you

The last push to the repository was on 2026-09-20, and the most recent release listed is v1.26.1 from 2026-06-10, preceded by v1.26.0 in April and v1.25.3 in March. That is a release cadence measured in months, with commits landing between releases. The repository is not archived. Anyone running it should expect to track the feed rather than pin to a release, because the feed install path pulls whatever the main branch currently ships.

The licence is GPL-3.0, stated in the repository and shown in the README badge, with the LICENSE file at the top level. For a router package that is unremarkable, but it has one practical consequence worth naming: if you build Nikki into a firmware image you distribute, the GPL obligations attach to that distribution. That is a description of the licence, not legal advice, and anyone shipping firmware should read the licence text rather than this paragraph.

The upgrade cost is mostly the profile. Because the run sequence rewrites the profile before starting the core, an upgrade that changes mixin behaviour can change what your rules resolve to without any visible change in the LuCI screen. The README does not document a rollback for a bad profile beyond the uninstall script, which removes the packages and resets rather than reverting to a previous profile. Keep your own copy of the profile outside the router.

Editorial conclusion

Nikki fits routers on OpenWrt 24.10 or newer with firewall4 and kernel 5.13 or newer, where the operator wants Mihomo profiles managed from LuCI and is willing to accept that the wiki, not the README, is the manual. It is the wrong choice on older OpenWrt releases that still use firewall3, or where the router's flash and RAM cannot carry the dependency set. Before adopting it, confirm the installed firewall version and kernel, then read the wiki page for the profile editor and the scheduled restart, because the README only lists feature names and never documents rollback beyond the uninstall script.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. nikkinikki-org/OpenWrt-nikki on GitHub
3. Project website
4. README
5. Releases