On this page
First, install the OpenClash plugin and Mihomo core so they run reliably
This tutorial gets the router itself working before moving on to subscriptions and whole-home access. Start by opening “Status → Overview” and recording the OpenWrt version, CPU architecture, and available memory. Then export a configuration backup from “System → Backup / Flash Firmware.” Router storage is often tight, so confirm that /overlay has free space before a package installation fails halfway through.
First, run the read-only command below over SSH. Continue with this guide's opkg installation path only if command -v opkg returns output. If the device has only apk, do not force the opkg commands onto it; follow the apk instructions on the current OpenClash release page.
ubus call system board
df -h /overlay
free -h
command -v opkgDownload only from the vernesong/OpenClash release page. In LuCI, open “System → Software → Upload Package,” upload the official ipk, and install it. For the SSH method, transfer the same file to /tmp/openclash.ipk.
OpenWrt 23.05 and later commonly use firewall4 with nftables, while older firmware may still use iptables. Choose only one of the two dependency sets below for your firewall; do not install both.
# 仅适用于 command -v opkg 有输出的固件
opkg update
# firewall4 / nftables 固件选这一行
opkg install bash dnsmasq-full curl ca-bundle ip-full ruby ruby-yaml kmod-tun kmod-inet-diag unzip kmod-nft-tproxy luci-compat luci luci-base
# 老的 iptables 固件改用这一行，不要和上一行同时执行
# opkg install bash iptables dnsmasq-full curl ca-bundle ipset ip-full iptables-mod-tproxy iptables-mod-extra ruby ruby-yaml kmod-tun kmod-inet-diag unzip luci-compat luci luci-base
opkg install /tmp/openclash.ipk
opkg status luci-app-openclashWhen installation finishes, refresh LuCI. An entry should appear under “Services → OpenClash.” Open “Plugin Settings → Version Update,” confirm that the core build matches the router architecture, then download or update the Meta core.
For manual core installation, the official directory is /etc/openclash/core/ and the filename is clash_meta. Until this step is complete, an accessible luci-app-openclash page still cannot process traffic.
Return to the OpenClash home page, start the service, and inspect the runtime log. If the process exits after a few seconds, use the log to address missing dependencies, insufficient space, or an exec format error before importing a subscription. Installation is complete only when the plugin, core, and logs are all healthy.
opkg status luci-app-openclash
ls -l /etc/openclash/core/
/etc/init.d/openclash enable
/etc/init.d/openclash restart
sleep 3
pgrep -af clash_meta
logread | grep -i openclash | tail -n 80How to tell whether installation is complete
- “Services → OpenClash” opens in LuCI
- The core architecture shown on the version-update page matches the router
- /etc/openclash/core/clash_meta exists and can start
- The clash_meta process is still present three seconds after restarting the service
- The logs show no missing dependencies, insufficient space, or executable-format errors
- OpenWrt still reaches the internet directly after OpenClash is disabled
Import it under “Configuration Subscriptions” and confirm that it actually loads
Open “Configuration Subscriptions,” add the Clash or Mihomo subscription address supplied by your provider, and trigger one manual update. A successful import must show all of the following: the file timestamp changes, policy groups and nodes appear, configuration validation passes, and the status page identifies the newly updated file as the active configuration.
If the page says the task finished but the node list is still empty, inspect the download log. HTTP 401, 403, a redirect to a sign-in page, a plan notice, or an empty file means the subscription content was not retrieved correctly. A YAML line number, unknown field, or group not found indicates a parsing problem. Hide the personal token in the URL while troubleshooting.
Enable a subscription for the first time
Update manually
Confirm that the file time and size changed, and record any HTTP error from the download stage.
Run configuration validation
Address YAML line numbers, unknown fields, and policy-group references first.
Set it as the current configuration
Return to the status page and confirm the filename actually loaded.
Pin one node
Do not use a benchmark group that automatically changes egress yet.
Once the subscription works, choose only one operating mode for the first test
OpenClash modes such as Fake-IP, Redir-Host, TUN, and mixed mode address different traffic-capture needs; enabling all of them does not make setup more complete. For the first run, use the common mode currently recommended by the plugin, generate connection records from one computer, and then handle compatibility issues in the few affected apps.
Fake-IP helps the core obtain domains earlier and apply rules, but LAN domains and a few apps may require exclusions. Redir-Host returns real resolution results and is easier to reason about. TUN captures more traffic from apps that ignore the system proxy, but it is also more likely to conflict with a VPN, policy routing, or hardware acceleration.
After switching modes, have the test computer renew its network address and clear its DNS cache, then visit the same site. If the old cache remains, it is easy to conclude incorrectly that the new mode did not take effect.
Before connecting the whole home, determine whether OpenWrt is the primary router or a secondary gateway
Whether OpenClash can process traffic from phones, TVs, and a NAS depends on those devices' default gateways, not on whether the plugin page says it is running. When OpenWrt is the primary router, LAN devices already pass through it. When it is a secondary gateway, only devices whose gateway points to OpenWrt enter OpenClash.
For the first secondary-gateway test, change the gateway and DNS on only one computer. After it can open a regular website, a site that needs proxying, and the router's management page, update DHCP. Switching every household device at once can make even the management page unreachable if DNS or the firewall is wrong.
Two home-network topologies
| Topology | What OpenWrt handles | How to roll back |
|---|---|---|
| OpenWrt as the primary router | Access, DHCP, DNS, and firewall services all run on the same device | After OpenClash is disabled, OpenWrt still connects directly |
| OpenWrt as a secondary gateway | The original primary router stays online, while selected devices use OpenWrt as their gateway | Set the test device's gateway and DNS back to the primary router |
The gateway determines where connections go; DNS determines whether rules can identify domains
When OpenWrt is the primary router, DHCP normally advertises its LAN address as both the default gateway and DNS server. During a secondary-gateway test, enter the secondary gateway's address manually on one computer; after verification, configure the primary router's DHCP to advertise it to selected devices. If two DHCP services assign addresses on the same subnet, connectivity becomes intermittent rather than reliably redundant.
Secure DNS in the browser, Android Private DNS, and built-in DoH in some TV apps may bypass the router. Temporarily disable these independent paths while troubleshooting so queries pass through dnsmasq and OpenClash. Once rule matching is stable, decide which encrypted DNS options to restore.
IPv6 must be evaluated too. If a device receives public IPv6 while OpenClash captures only IPv4, some connections will go out directly over IPv6. Handle IPv6 routing and resolution explicitly instead of blaming every intermittent direct connection on the node.
- NAS devices, printers, and router dashboards
- Private subnets and local domains should remain direct; first confirm that management access is not captured.
- Game consoles and TVs
- They rarely provide detailed errors, so add them only after computers and phones have been verified.
- Secondary gateway
- Both the gateway and DNS on the test device must point to the secondary gateway; changing only one verifies only half the path.
- Phone or computerReceives the gateway and DNS from DHCP
- OpenWrtReceives connection and resolution requests from endpoints
- OpenClashChooses egress according to the configuration and rules
- Target serviceReceives the request through a direct or proxied path
In a secondary-gateway setup, you cannot change only the gateway or only DNS. When the two paths disagree, pages may open intermittently while rule matches and resolution results remain unstable.
Verify in order, starting on the router itself and then moving to one endpoint
A verification sequence that produces useful evidence
Test the router itself first
Confirm that system time is correct, WAN connectivity works, and the subscription domain resolves.
Then inspect core status
The configuration loads successfully, a pinned node produces a connection result, and the logs show no restart loop.
Connect one computer
Do not configure a browser extension proxy; rely only on the new gateway and DNS.
Compare three address types
Visit a domestic site, a site that requires proxying, and the router management page, then compare the connection records.
If the router itself can connect but a downstream computer cannot, check DHCP, the gateway, and firewall forwarding first. If domains fail but an IP request responds, investigate DNS. Return to rules and policy groups only when connection records appear but outbound traffic fails. This sequence is faster than repeatedly restarting OpenClash.
Roll out whole-home access in batches by device type
After one computer and one phone are stable, add TVs, game consoles, and smart-home devices. Keep the original gateway and DNS for every newly added device type; if problems appear, return that device type to direct access first. Once the home network recovers, you can inspect logs and rules methodically.
Before making the final DHCP change, document how to disable OpenClash, restore the original DNS, and enter failsafe. Subscription updates, firmware upgrades, and core replacements can all change behavior. A management path that does not depend on OpenClash prevents one plugin failure from taking the entire home offline.