Back to Blog
Home/ Blog/ Complete Guide to Setting Up Clash CLI on Linux

Complete Guide to Setting Up Clash CLI on Linux

2026-08-01 Reading time: ~ 7 min

Table of Contents

Introduction to Clash CLI on Linux

Running a proxy client on Linux without a graphical user interface requires a robust command-line solution. The Clash CLI, specifically the actively maintained Clash Meta (mihomo) core, provides enterprise-grade routing, protocol support, and performance for Linux servers and headless desktops.

While desktop users might prefer GUI clients, understanding the CLI setup is crucial for server administrators and power users. If you are actually looking to set up a graphical client on a Windows desktop instead, please refer to our Clash for Windows installation guide. For this tutorial, we will focus entirely on the headless Linux environment, ensuring you have a fully automated, system-level proxy.

Prerequisites and System Requirements

Before proceeding with the clash linux setup, ensure your environment meets the following requirements:

Architecture Matters

Ensure you download the correct binary for your CPU architecture. Most modern servers use amd64 (x86_64), but ARM-based servers (like AWS Graviton or Raspberry Pi) require the arm64 binary.

Downloading and Installing the Clash Meta Core

The original Clash core is archived. We will use mihomo, the community-driven successor that supports all modern protocols like VLESS, TUIC, and Reality.

Step 1: Download the latest release

Fetch the latest mihomo binary from the official GitHub repository. Replace the version number with the latest available release.

wget https://github.com/MetaCubeX/mihomo/releases/download/v1.18.10/mihomo-linux-amd64-v1.18.10.gz
Step 2: Extract and install the binary
gunzip mihomo-linux-amd64-v1.18.10.gz
chmod +x mihomo-linux-amd64-v1.18.10
sudo mv mihomo-linux-amd64-v1.18.10 /usr/local/bin/mihomo
Step 3: Verify the installation
mihomo -v

This should output the version information, confirming the core is correctly installed in your system path.

Configuring the Clash YAML File

Clash relies on a YAML configuration file to define proxies, rules, and DNS settings. We will store this in /etc/mihomo/.

Step 1: Create the configuration directory
sudo mkdir -p /etc/mihomo
sudo touch /etc/mihomo/config.yaml
Step 2: Populate the configuration

You can manually write your configuration or download it directly from your subscription provider. For a manual setup, a minimal configuration looks like this:

mixed-port: 7890
allow-lan: false
bind-address: '*'
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - 8.8.8.8
    - 1.1.1.1

proxies:
  - name: "us-node-1"
    type: vless
    server: us1.example.com
    port: 443
    uuid: your-uuid-here
    network: ws
    tls: true
    udp: true

For a deep dive into every parameter, read our Clash YAML configuration explained guide. If you need to route specific traffic based on domains or IPs, check out the Clash rule configuration tutorial.

Subscription Conversion

If your provider only gives a subscription URL, you can use curl to download it directly: curl -o /etc/mihomo/config.yaml "YOUR_SUBSCRIPTION_URL". Ensure the URL returns valid YAML, not an HTML login page.

Setting Up Systemd Service for Auto-Start

To ensure Clash starts automatically on boot and restarts on failure, we must create a systemd service.

Step 1: Create the service file
sudo nano /etc/systemd/system/mihomo.service

Paste the following configuration:

[Unit]
Description=mihomo Daemon, Another Clash Kernel.
After=network.target NetworkManager.service systemd-networkd.service

[Service]
Type=simple
LimitNPROC=500
LimitNOFILE=1000000
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_TIME CAP_SYS_PTRACE CAP_DAC_READ_SEARCH CAP_DAC_OVERRIDE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE CAP_SYS_TIME CAP_SYS_PTRACE CAP_DAC_READ_SEARCH CAP_DAC_OVERRIDE
Restart=always
ExecStartPre=/usr/bin/sleep 1s
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target
Step 2: Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable mihomo
sudo systemctl start mihomo

Check the status to ensure it is running without errors:

sudo systemctl status mihomo

Configuring System Proxy and Environment Variables

Unlike desktop environments, a headless Linux server does not automatically route traffic through the local proxy. You must configure your applications or shell environment to use it.

Global Shell Proxy

To route terminal commands (like apt, curl, git) through Clash, add the following to your ~/.bashrc or ~/.profile:

export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"
export all_proxy="socks5://127.0.0.1:7890"
export no_proxy="localhost,127.0.0.1,::1"

Remember to run source ~/.bashrc to apply the changes immediately.

TUN Mode Requirements

If you want to route all system traffic transparently without setting environment variables, you must enable TUN mode in your config.yaml and grant the mihomo binary the cap_net_admin capability using sudo setcap cap_net_admin=+ep /usr/local/bin/mihomo. Note that TUN mode requires the tun device support in your kernel.

Managing Clash via the RESTful API

Even without a GUI, you can manage your Clash instance using web-based dashboards that connect to the RESTful API.

Step 1: Verify API binding

Ensure your config.yaml contains the following line to expose the API locally:

external-controller: 127.0.0.1:9090

If you need to access the dashboard from another machine on your local network, change 127.0.0.1 to 0.0.0.0, but be sure to configure secret for security.

Step 2: Access the Web Dashboard

Open a browser on your local machine and navigate to a web dashboard like Yacd or MetaCubeXD. For example, using MetaCubeXD:

http://d.metacubex.one/#/setup?api=http://YOUR_SERVER_IP:9090

From here, you can switch nodes, update subscriptions, view real-time traffic logs, and manage rules without touching the CLI.

Troubleshooting Common Issues

When performing a clash linux setup, you might encounter a few common hurdles. Here is how to resolve them.

Port Already in Use

If mihomo fails to start and logs indicate port 7890 or 9090 is in use, another process is occupying it. Find the culprit with:

sudo lsof -i :7890

Kill the process or change the mixed-port in your configuration file.

YAML Parsing Errors

Clash is strict about YAML syntax. A missing space or incorrect indentation will cause the service to crash. Always validate your configuration before restarting the service:

mihomo -d /etc/mihomo -t

The -t flag tests the configuration file and outputs detailed error messages if the syntax is invalid.

DNS Resolution Failures

If you can ping IP addresses but cannot resolve domain names, your DNS configuration in config.yaml might be flawed. Ensure you are not mixing fake-ip mode with incompatible nameservers. Sticking to standard DoH (DNS over HTTPS) or plain UDP nameservers like 8.8.8.8 is recommended for initial setups.

Related Articles