Skip to content
Get packs

Guide · Open source

How to use OpenClash on OpenWrt: install, configure and route traffic

Updated · written with AI from the project's own documentation and checked against our catalogue data

OpenClash is a LuCI web-interface add-on for OpenWrt, the Linux-based router firmware. It manages the Mihomo (Clash Meta) proxy core so devices on your home network can send traffic through proxy servers according to rules you write. This guide walks through checking prerequisites, installing the package, and getting a first configuration running.

OpenClashvernesong/OpenClash · ★ 28k · MIT

Quick start

  1. 1Confirm OpenWrt and LuCI. Check that your router runs OpenWrt with LuCI, and that the package manager is opkg or apk.
  2. 2Update package lists. Run opkg update or apk update so the router knows the latest packages.
  3. 3Install dependencies. Install the dependencies listed in the README for your firewall type, such as bash, curl, ruby, ruby-yaml and dnsmasq-full.
  4. 4Install the OpenClash package. Download the release .ipk or .apk and install it with opkg install or apk add.
  5. 5Import your subscription. In LuCI, open Services → OpenClash and import a subscription or upload a configuration file.
  6. 6Start and test. Start the service, let the core download, then check that traffic from your devices follows the rules you set.

Check what you need before installing OpenClash

OpenClash only runs on OpenWrt with LuCI installed. It is installed into the router's LuCI interface and will not run on an ordinary PC or phone. The README lists Luci 19.07 or newer for luci-compat.

You also need a package manager on the router: opkg (for .ipk files) or apk. The dependencies include bash, curl, ruby, ruby-yaml and dnsmasq-full. kmod-tun is optional and is needed for TUN mode.

  • OpenWrt with LuCI
  • opkg (ipk) or apk on the router
  • Dependencies such as bash, curl, ruby, ruby-yaml, dnsmasq-full
  • kmod-tun (optional, for TUN mode)

Install OpenClash with opkg or apk

The simplest route is the web install: download the .ipk or .apk from the Releases page, open System → Software in LuCI, upload and install it. The README also gives command-line installs. The commands below are the README's package-update and install lines for the release file.

Choose the firewall path that matches your router. The README gives separate dependency lists for iptables and for nftables (Firewall4). The full command blocks in the README install the dependencies and fetch the latest release automatically.

opkg update opkg install /tmp/openclash.ipk apk update apk add -q --force-overwrite --clean-protected --allow-untrusted /tmp/openclash.apk

Import a subscription or config file and start OpenClash

After installing, refresh or log in again to the LuCI page. In the README's web-install steps, you open Services → OpenClash, then import a subscription or upload a configuration file, and start the service.

OpenClash supports multiple subscriptions and multiple configuration files, and you can switch between them from one place. The README also notes that the first use needs to download the core, so confirm your network connection beforehand.

  • Open Services → OpenClash in LuCI
  • Import a subscription or upload a config file
  • Start the service
  • Make sure the network allows the core download on first run

Set up rules and traffic routing

OpenClash routes traffic according to rules you configure. The README describes transparent proxying, redir-host / fake-ip and mixed modes, and TUN mode, with support for iptables and nftables.

Access control features include black and white lists and custom firewall rules. Streaming services such as Netflix, Disney+ and HBO can be set to auto-select a line. Modular override YAML lets you customise configuration files.

  • Transparent proxy with redir-host, fake-ip or mixed mode
  • TUN mode (needs kmod-tun)
  • Black and white lists and custom firewall rules
  • Override YAML for config customisation

Back up and manage configurations

The README lists online editing of configuration files, backup and restore, and Age encryption for configs. Keep a backup before changing firewall or proxy settings so you can return to a known working state.

Subscriptions can be converted online with Subconverter, and you can set a custom User-Agent and request headers for subscription fetches.

  • Online editing of config files
  • Backup and restore
  • Age encryption
  • Subconverter online conversion

What people use it for

  • Routing the whole home network through proxy servers based on rules, without installing software on each device
  • Managing several proxy subscriptions and configuration files from one LuCI page
  • Splitting traffic per device or per site on a home router
  • Using streaming node auto-selection for Netflix, Disney+ or HBO

Frequently asked questions

Is OpenClash free?

OpenClash is released under the MIT licence, as stated in the project's listing. The licence applies to the code; check the repository for any terms that apply to subscriptions you import.

What hardware or software do I need to run OpenClash?

You need a router running OpenWrt with LuCI, plus opkg or apk on the router. The README lists dependencies such as bash, curl, ruby, ruby-yaml and dnsmasq-full, with kmod-tun optional for TUN mode.

Can I install OpenClash on Windows or Android?

No. The project is a LuCI plugin for OpenWrt routers and will not run on ordinary PCs or phones. Its README says it is aimed at router deployments.

Which protocols does OpenClash support?

The README says it works with Shadowsocks, ShadowsocksR, VMess, VLESS, Trojan, Snell, TUIC and Hysteria, among others, through the Mihomo (Clash Meta) core.

What alternatives are there to OpenClash?

The project listing names luci-app-clash, Passwall, SSR Plus+ and Shadowsocks-OpenWrt as comparable projects. Compare them on the protocols and firewall modes you need.

Why won't OpenClash start after installing?

Start by checking that all listed dependencies installed, especially dnsmasq-full and kmod-tun if you use TUN mode, and that the first-run core download could reach the internet. The README asks you to confirm the network before first use.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

OpenClash suits people who already run OpenWrt and want rule-based proxy routing for their whole network, with several subscriptions managed in one place. It is a poor fit for anyone without an OpenWrt router or without experience configuring a router, in which case a desktop proxy app is simpler.

Install options & downloads