On this page
An accessible OpenClash page does not establish that the router can proxy internet traffic. The plugin, dependencies, and core must suit the current firmware, and the subscription must pass validation and be selected as the active configuration. A missing configuration on first installation should not be mistaken for a core failure. Preserve management access and the original settings, test one device with one operating mode, then connect other devices after verification passes.
Requirements for Installing the OpenClash Plugin and Mihomo Core
Check the OpenWrt version, CPU architecture, and available memory under Status → Overview, and export your configuration under System → Backup / Flash Firmware. Check free space in /overlay before installation to avoid running out of space midway.
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.
Confirm that the core file runs through the status page or version output. On a first installation without a valid configuration, continue to subscription import. For exec format error, missing dependencies, or a non-executable file, fix architecture, dependencies, or permissions. Start the proxy service only after selecting a valid configuration.
opkg status luci-app-openclash
ls -l /etc/openclash/core/
/etc/openclash/core/clash_meta -vOpenWrt should still have direct internet access after OpenClash is disabled.
Import Under “Configuration Subscriptions” and Load It as the Active Configuration
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.
Start OpenClash after the configuration passes validation and is selected on the status page. If no configuration is available, return to subscription import. If logs show architecture, dependency, or executable-file errors, fix the corresponding installation problem. Test traffic capture only once the service keeps running and produces connection records.
opkg status luci-app-openclash
ls -l /etc/openclash/core/
/etc/init.d/openclash enable
/etc/init.d/openclash restart
sleep 3
ubus call service list '{"name":"openclash"}'
logread | grep -i openclash | tail -n 80Find openclash and its instances in the output. An instance’s running value of true together with a pid indicates that the process is running. If it is false or no instance is listed, check the status and logs. A running process does not prove that connectivity has recovered; complete the later client-device access tests as well.
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.
Gateway and DNS Settings for Main and Secondary Routers
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 |
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
- In this guide’s setup, the side router provides both the gateway and DNS, so both settings on the test device should point to it. Changing only one does not establish that this setup is complete.
- 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
This example uses the side router for both the gateway and DNS. Check both settings during testing. If you use a different DNS service, verify the query path, matched rules, and resolution results separately; changing the gateway alone does not establish that the setup is complete.
Once the Router Has Internet Access, Test Access from One Client Device
Access tests for the router and one computer
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 can connect but the downstream computer cannot, check DHCP, the gateway, and firewall forwarding. If domain requests fail but IP requests respond, check DNS. If a connection is recorded but uses the wrong exit, check rules and policy groups.
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.