# clashctl: a shell-based installer and manager for mihomo and Clash on Linux

> nelvko/clash-for-linux-install wraps the mihomo/Clash kernel, a web panel and subscription handling behind a single clashctl command. It suits headless Linux and container hosts where you want a proxy service without editing YAML by hand.

**nelvko/clash-for-linux-install** — 😼 优雅地使用基于 clash/mihomo 的代理环境

- Repository: https://github.com/nelvko/clash-for-linux-install
- Stars: 14,901 · Forks: 1,642
- Language: Shell
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/nelvko-clash-for-linux-install

## What clashctl actually solves on a Linux host

Running mihomo or Clash on a Linux server usually means three separate chores: fetching a kernel binary that matches the architecture, writing a config directory the daemon will accept, and registering a service so it survives a reboot. The repository bundles those steps into one script and then keeps them reachable through a command named clashctl. The README describes the project as a one-click deployment and management tool for the mihomo / clash kernel, covering the kernel, a web panel and runtime dependencies.

The target user is not someone with a desktop. It is someone on a VPS, a home server or a container who wants the proxy running as a background service and wants to switch subscriptions or nodes without hand-editing YAML. The README states support for both root and ordinary users, for mainstream Linux distributions, for container environments, and for systemd and OpenRC init systems. That last detail matters: many similar shell installers assume systemd and quietly fail on Alpine or on other OpenRC hosts.

## How the install script, clashctl and subconverter fit together

The repository is a Shell project. The top level holds install.sh, uninstall.sh, a scripts directory, a resources directory, an archives directory, and two environment files, .env and .env.install. The README points to .env.install as the place to customise installation options, which means the installer reads its defaults from a file rather than from flags only.

After installation, clashctl is the single entry point. The README's quick start shows it managing proxy on and off, kernel status, the web panel address, subscriptions and node switching, and the help output for the full command list. Subscriptions are handled as named sources: you add a URL, update it, and switch between sources. The README also states integration with subconverter, the external converter project, so subscription formats that the kernel does not read directly can be converted. The topics list confirms the same set of moving parts: clash, clash-meta, linux, mihomo and subconverter.

One release is listed, tagged clash (Clash Premium), dated 2026-03-31. The README separately describes clashctl as able to upgrade the kernel, so kernel version and tool version move independently.

## Installing it and running a first subscription

The README gives one installation command. It clones the master branch shallowly through an acceleration prefix and runs install.sh. The README notes that the prefix can fail and that other mirrors are listed elsewhere, so treat that hostname as replaceable rather than fixed.

```bash
git clone --branch master --depth 1 https://gh-proxy.org/https://github.com/nelvko/clash-for-linux-install.git \
  && cd clash-for-linux-install \
  && bash install.sh
```

Before running it, the README says installation options can be customised through the .env.install file in the repository root. Read that file first if you care where the kernel lands or which init system gets used.

Once the script finishes, the README's quick start uses clashctl for everything. The commands below are copied from that list: turn the proxy on, check the kernel, print the panel address, add a subscription, update it, and switch node.

```bash
clashctl on
clashctl status
clashctl ui
clashctl sub add <url>
clashctl sub update
clashctl node
```

Run clashctl -h for the full command set. The README does not document what each command prints, so expect to read the output rather than match it against a documented format. Removal is a separate script in the project directory.

```bash
bash uninstall.sh
```

## Where this approach breaks down

The installer pulls a kernel binary from the network. That is inherent to a one-click tool of this shape, but it means the trust boundary is the download, not the repository. The README does not document checksum verification or signature checking for the kernel, and it does not document rollback if an upgrade produces a kernel that will not start. The upgrade path is one-directional as far as the documentation shows.

Second, this is a command-line service manager, not a desktop client. There is no native GUI; the README's answer to interface needs is a web panel address printed by clashctl ui. If you want tray icons, per-application routing rules edited by mouse, or profile switching from a window, this is the wrong tool and a desktop client is the right one.

Third, the project's own disclaimer is unusually direct. It states the main purpose of writing the project was to study and research Shell programming, and that nothing in it should be used in ways that violate applicable laws or regulations. That is a statement about the author's intent, and it shifts the compliance question entirely onto whoever runs the installer.

Finally, the README documents no configuration schema for the kernel itself. If you need to hand-tune rules, DNS behaviour or TUN parameters beyond what clashctl exposes, you are working in files the README does not describe.

## How it differs from a desktop Clash client

The obvious alternative for Linux users is a graphical client such as Clash Verge, which is a desktop application with a window, profile management and system tray integration. The difference is not cosmetic. A desktop client owns the session: it starts when you log in, it exposes settings through a UI, and its lifecycle is tied to your graphical session. clash-for-linux-install does the opposite. It installs a kernel plus a service, so the proxy is up before anyone logs in and stays up on a headless machine with no display at all.

That trade runs both ways. The service model is what you want on a server and what you do not want on a laptop where you toggle the proxy by hand. The README's clashctl on and clashctl off commands are the closest thing to that toggle, and they are terminal commands, not menu items. The project also bundles subconverter, which a desktop client may or may not do; that matters if your subscription provider hands out a format the kernel will not read directly.

## Maintenance, upgrades and what the MIT licence leaves open

The repository is not archived, and the last push was on 2026-09-21. The single listed release, tagged clash (Clash Premium), is dated 2026-03-31, so the tool and the kernel it ships have separate timelines. The README states that clashctl can upgrade the kernel, which is the main recurring maintenance action; the rest is subscription updates through clashctl sub update.

The licence is MIT, which is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are kept. It comes with no warranty. The repository also carries a disclaimer that the author reserves the right to amend, and that anyone using the project directly or indirectly is treated as accepting it. That disclaimer sits alongside the licence rather than replacing it, and it is a statement of intent about lawful use, not a technical control. Nothing in the licence or the disclaimer checks what you route through the proxy or where the kernel binary came from. If you are deploying this inside an organisation, the questions to settle are the ones the repository cannot answer for you: which kernel build is acceptable, and who reviews install.sh before it runs.

## Conclusion

Adopt it if you run a headless Linux box or container and want mihomo running as a service with subscription switching from one command. Do not adopt it if you need a graphical desktop client, or if you are not willing to accept that the kernel it installs is a third-party binary and that the maintainer's disclaimer limits the project to study and research. Before committing, check that the install path works on your distribution and init system, confirm which kernel build install.sh pulls and where it writes it, and read uninstall.sh to see exactly what it removes. The project's own boundary is stated in the README: it exists for learning and researching Shell programming.

## FAQ

### How do I install clash-for-linux-install on Ubuntu?

The README gives a single command that shallow-clones the master branch through an acceleration prefix and runs install.sh. It states support for mainstream Linux distributions, root and ordinary users, and both systemd and OpenRC init systems, so Ubuntu is covered by that claim rather than by a distro-specific instruction.

### Does clash-for-linux-install include a GUI?

No native desktop interface is documented. The README exposes a web panel instead, whose address is printed by the clashctl ui command. If you need a windowed client with tray integration, a desktop application is the right category of tool.

### How do I add and update a subscription with clashctl?

The README's quick start shows clashctl sub add <url> to add a source and clashctl sub update to refresh it, with clashctl node to switch between nodes. The README also states that subconverter is integrated for converting subscription formats.

### How do I uninstall clash-for-linux-install?

Run bash uninstall.sh from the project directory. The README describes this as a clean removal that clears the kernel, the configuration and the service. It does not document a partial or per-component removal.

### Can I use clash-for-linux-install in Docker?

The README states that container environments are among the supported targets, alongside root and ordinary users and systemd or OpenRC init systems. The documentation does not give a container-specific command or image, so the install path stays the same script.

## Sources

- [Issues](https://github.com/nelvko/clash-for-linux-install/issues)
- [License: MIT](https://github.com/nelvko/clash-for-linux-install/blob/master/LICENSE)
- [nelvko/clash-for-linux-install on GitHub](https://github.com/nelvko/clash-for-linux-install)
- [README](https://github.com/nelvko/clash-for-linux-install/blob/master/README.md)
- [Releases](https://github.com/nelvko/clash-for-linux-install/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nelvko-clash-for-linux-install