clash-for-linux: a shell-driven Clash / Mihomo runtime for Linux servers

What clash-for-linux actually manages

The project is a control layer around the Clash / Mihomo kernel, written in Shell and distributed under the MIT licence. Its stated audience is people running Linux cloud servers, remote development environments, local Ubuntu or Debian machines, WSL, and lightweight devices such as OpenWrt routers or NAS boxes. The README also names developers who need steady access to GitHub and the Go, Node and Docker ecosystems.

The problem it addresses is operational rather than functional. The Mihomo core already does the proxying; what it does not do is remember several subscriptions, pick a free port, keep a running configuration separate from a repository, or tell you why something stopped working. clash-for-linux adds those pieces as commands: clashon, clashoff, clash select, clash mode, clash add, clash use, clash doctor. It is not a graphical client, and the README never presents it as one.

The Control, Build and Runtime split

The README describes the architecture in three layers. Control is the user entry point: clash, clashon, clashoff, status, doctor, ui and select. Build generates configuration. Runtime holds everything the running process needs.

The Build layer is where the interesting constraint lives. Multiple subscriptions are stored, but only one is active at a time, and the README states plainly that generate_config only processes the current active subscription. A mixin file at runtime/mixin.yaml (with a compatibility read of config/mixin.yaml) is appended or overlaid onto the generated result, and the output lands at runtime/config.yaml.

runtime/ is described as a runtime directory, not a configuration directory. It holds the kernel binary, the running config, subscriptions.yaml, the dashboard frontend, logs and build intermediates. The README is explicit that these are generated during install or at run time and are not maintained as repository content. That separation is the main reason upgrades are less messy than they would be otherwise: the repository can be replaced without touching subscription state.

Installing clash-for-linux and running the first commands

The README recommends a one-line install from a shallow clone, using a GitHub acceleration prefix that it notes can be swapped for another mirror if it stops working.

 git clone --branch master --depth 1 https://ghfast.top/https://github.com/wnlen/clash-for-linux.git
 cd clash-for-linux
 bash install.sh

Install options can be customised through a .env file or script arguments. WSL users are told not to place the project under the Windows mount at /mnt/c/; it must live on a native Linux path.

Once installed, the everyday commands are short. The block below turns the proxy on and off and checks which routing mode is active.

clashon
clash mode
clashoff

clash mode with no argument prints the current routing mode; the README lists rule, global and direct as the switchable values. Adding a subscription takes a link and a name, and clash use switches which one is active.

clash add <订阅链接> <名称>
clash use
clash ls

A local YAML file can be imported instead of a remote link. The README recommends the interactive form and documents where the file should sit.

clash add local
# 输入：clash.yaml

That is equivalent to clash add "file://$PROJECT_DIR/runtime/subscriptions/clash.yaml". The README also lists accepted formats: Clash / Mihomo YAML, Base64 subscriptions, and share links in vmess, vless, trojan, tuic, hysteria2, hy2 and anytls form.

Finally, clashui prints the web console address, the port to open, and the current secret. The README's example output shows port 9090 and a LAN URL of the form http://192.168.0.1:9090/ui. The default frontend is zashboard.

Diagnostics, routing modes and the connectivity test

clash doctor is the built-in diagnostic panel, and clash log or clash logs reads the log. These two are the practical answer to "the proxy stopped working and I do not know why".

The connectivity test has a detail worth knowing: clash test and clashtest are equivalent, and both test whether the currently selected policy group can reach Google and YouTube, printing latency. The README states that the test does not switch nodes, and that it returns a non-zero status when either target is unreachable. That makes it usable as a script gate rather than just an interactive check. A policy group or node name can be passed as an argument, as in clashtest "节点选择".

Routing modes are rule, global and direct. In global mode the README says the GLOBAL policy group's current selection is used, and that clash select is how you change it. This is a small but real distinction: switching to global without checking what GLOBAL points at can send traffic somewhere you did not intend.

Where clash-for-linux runs into limits

The OpenWrt support is the clearest boundary. The README describes it as a script mode that reuses the existing script runtime backend. It does not include procd startup, LuCI, UCI or opkg packaging, and the README states it does not promise MIPS or armv7 device support. Only x86_64/amd64 and aarch64/arm64 are named as suitable. In script mode there is no boot autostart either: after a device reboot you must run clashon again.

Tun mode, which the README describes as being for transparent proxy interception, requires a root install. That is a hard prerequisite, not a preference.

Permissions are the second boundary. On WSL or as an ordinary user without write access to /etc/environment, clashon degrades: the runtime starts and the current shell's proxy variables take effect, but system-wide persistent proxy takeover and boot proxy are unavailable. The README says this downgrade happens automatically, which is convenient, but it also means a user can believe the proxy is set up system-wide when it is only set for one shell.

The README does not document a rollback path for a bad mixin or a broken subscription, and it does not describe what happens to in-flight traffic when the kernel is upgraded. Those are omissions, not features.

clash-for-linux against a desktop client

The obvious alternative is a graphical client such as Clash Verge, which is a desktop application with a window, and which the search data shows people asking about for Ubuntu. The difference in approach is not cosmetic. A desktop client assumes a logged-in user session, a tray icon and a GUI to click through. clash-for-linux assumes a terminal and a service-like lifecycle: install once, run commands, read logs, and optionally register boot takeover through clash boot.

On a headless VPS there is no session to attach a tray icon to, which is why the command layer exists. On a laptop where you want to toggle nodes by clicking, the shell tool is the wrong shape. The two are not substitutes for the same job.

Within the shell category, the distinguishing choices here are the active-only build chain (one subscription compiled at a time) and the mixin overlay, which let a user patch generated configuration without editing the subscription itself.

Maintenance cost, licence and upgrade paths

The repository was last pushed on 2026-08-31, and it is not archived. The only release listed is v1.0.1, dated 2026-04-14 and labelled "Clash for Linux Premium".

Upgrades are split in two. clash update refreshes the project code, while clash upgrade updates the current kernel or a specified one. Because runtime/ is generated rather than tracked, replacing the code does not necessarily discard subscription state, which is the design intent stated in the README. The mixin file is the exception worth watching: it lives in runtime/ and is read at build time, so a code update that changes the build chain is the moment to re-check it.

The licence is MIT. That is permissive, and it places no copyleft obligation on the surrounding scripts. It says nothing about the Mihomo kernel, which is a separate project with its own terms, and nothing about the subscription services a user points the tool at. Those are separate questions the README does not address, and they are not legal advice.

Editorial conclusion

Adopt it if you run a headless Linux box, VPS or WSL environment and want subscription switching, port detection and a diagnostic command without hand-editing YAML. Skip it if you want a desktop GUI with tray icons, or if you need MIPS or armv7 OpenWrt support, which the README explicitly does not promise. Before installing, confirm the target directory is a native Linux path (WSL users must avoid /mnt/c/), decide whether you need a root install for Tun mode, and check that ports 9090 and 7890 are free or that the automatic port detection has something to work with.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. wnlen/clash-for-linux on GitHub