Clash Cross-Platform Setup Guide

1. General preparation

No matter the platform, setting up a working Clash environment breaks down into four steps: pick and download a client, import your subscription, choose a proxy mode, then turn the proxy on and verify it works. The differences between platforms come down to how you install the app and how the system takes over traffic — the main thread stays the same. This chapter covers the three things common to every platform before the platform-specific chapters dive in.

Which client to pick

The clients listed on our download page are organized by platform below. Clash Plus is the top pick everywhere — the widest coverage and a consistent interface, so you don't have to relearn anything when you switch devices. The alternatives each have their own strengths; see the feature comparison for details.

Clash for Windows and ClashX Meta are both discontinued. The download page still keeps an archive link for them, but they're not recommended for new setups — the core version is frozen, so newer rule types and protocol features aren't available.

Get a subscription link ready

A subscription link is an https address provided by your proxy service in its user panel; the client periodically fetches it to pull the node list and routing configuration. Before installing anything, copy this link in full to your clipboard. Be careful not to confuse it with a single-node share string that starts with a protocol name — a subscription link points to a full configuration and produces node groups on import, while a single-node string describes just one node and imports differently. Don't mix the two up.

Three concepts to understand first

System proxy vs. TUN mode. A system proxy writes "point HTTP/SOCKS traffic to a local port" into the OS network settings; browsers and most apps that respect system settings will follow it, but command-line tools, some games, and apps that ignore system settings will bypass it. TUN mode creates a virtual network adapter and takes over all traffic at the network layer — full coverage, at the cost of needing higher system privileges. Use the system proxy for everyday browsing, and switch to TUN when you need to capture everything.

Rule, Global, and Direct modes. Rule mode matches traffic against the routing rules in your config file one by one, and once it hits a match it routes traffic via proxy or direct connection accordingly — this is the recommended default. Global mode sends all traffic through the same proxy exit, useful as a temporary fallback when rules aren't working as expected. Direct mode proxies nothing, useful as a baseline for troubleshooting. All three can be switched with one tap in every client.

The local port. By default Clash exposes a mixed proxy port (HTTP and SOCKS on the same port) at 127.0.0.1:7890 — this is the mixed-port setting in the config. Any tool that needs a manually specified system proxy should point to 127.0.0.1:7890. If another app is already using that port, the client will fail to start or the proxy won't work — see Chapter 8 for how to change the port.

2. Windows

Download and install

Grab the installer from the Windows section of the download page — Clash Plus is the top pick, and the x64 build covers most machines. When you double-click the installer, Windows SmartScreen may show a "Windows protected your PC" warning — this is the default block for installers that haven't been widely distributed yet. Click "More info," then "Run anyway," to continue. Leave the install path at its default; installing into a deep folder with non-ASCII characters or spaces occasionally causes the core to fail on launch, so there's no reason to risk it.

Import a subscription

After the first launch, go to the Subscriptions (or "Profiles") page, paste your subscription link, and click Import. The client downloads and parses the config — success looks like a node group and node list appearing on the proxy page. If the list stays empty or you get an error, first open the subscription link directly in a browser to confirm it returns content, then work through the subscription troubleshooting checklist step by step.

System proxy and TUN

Toggling "System Proxy" in the client writes 127.0.0.1:7890 into Windows' Internet proxy settings, and browsers pick it up immediately. Turning on TUN mode has one extra requirement: creating the virtual network adapter needs administrator privileges. Clash Verge Rev handles this by having you install a "Service Mode" component in settings first — once that background service is running, the TUN toggle becomes available and no longer needs a manual privilege prompt each time. Clash Plus instead asks for authorization once, the first time you turn TUN on. Once TUN is on, you can leave the system proxy switch off — there's no need to run both.

Windows-specific issues

• Port conflicts. Thunder, dev tools, and similar apps often grab ports near 7890. If the client log shows bind: address already in use, change mixed-port to a free port like 7897 in the config or client settings.
• Autostart. Enable "Start on boot" in client settings. If you also want TUN mode active right after boot, install Service Mode first — otherwise TUN will silently fail on autostart due to insufficient permissions.
• False antivirus flags. Because the proxy core works by forwarding network traffic, some antivirus software flags it as suspicious and quarantines the core binary, which shows up as repeated "core failed to start" errors. Add the install folder to your antivirus's trusted list — the mihomo core's source code is publicly available for review.
• UWP apps ignoring the proxy. Store apps are blocked by default from reaching the local loopback address, so they can't reach the proxy port at 127.0.0.1. Some clients offer a "UWP loopback exemption" tool where you can check off the store apps that need proxying; alternatively, switch to TUN mode to bypass the restriction entirely.

3. macOS

Pick the right chip architecture

The macOS installer comes in two builds: Apple Silicon (M-series chips) and Intel. If you're not sure which one you have, click the Apple menu → "About This Mac" — if "Chip" starts with "Apple M," get the Apple Silicon build; if it says "Intel," get the Intel build. The macOS section of the download page has separate buttons for each. Installing the wrong architecture typically means the app won't launch, or runs slowly under translation.

First launch and Gatekeeper

The first time you open a dmg downloaded from a browser, macOS may say "can't be opened because Apple cannot check it for malicious software." Two ways around it: right-click the app icon in Finder and choose "Open," then click "Open" again in the dialog; or go to System Settings → Privacy & Security, scroll down to find the blocked app, and click "Open Anyway." If you instead see "app is damaged," the downloaded file has a quarantine flag — remove it with one Terminal command (swap in the actual app name):

xattr -dr com.apple.quarantine /Applications/Clash\ Plus.app

Subscription import and system proxy

Subscription import works the same as on Windows: paste the link on the subscriptions page, import, and confirm the node list appears. Turning on "System Proxy" writes HTTP, HTTPS, and SOCKS proxy settings into the currently active network service (Wi-Fi or Ethernet) via a system API, and reverts automatically on a normal quit. If the client crashes unexpectedly, the proxy settings can be left behind and cut off your internet — clear them manually under System Settings → Network → your active network's "Details" → "Proxies," by unchecking each proxy protocol.

TUN, autostart, and other notes

Enabling TUN on macOS requires system authorization: the client will walk you through installing a privileged helper or system extension, prompting for your admin password along the way — this is normal, and the authorization only needs to happen once. Turning on autostart in client settings registers it as a system "Login Item," which you can confirm under System Settings → General → Login Items. Two more things to keep in mind: the system proxy only applies to the currently active network service, so check the toggle again after switching adapters; and ClashX Meta is discontinued — only recommended for older machines that can't run the newer clients, otherwise pick Clash Plus or Clash Verge Rev on any new machine.

4. Android

Download and install

Get the APK from the Android section of the download page. Most modern phones need the arm64 build; older devices or TV boxes might be armv7, and installing the arm64 package on those will show a compatibility error — switch to the arm build in that case. The first time you install an APK downloaded from a browser, Android will ask you to grant "Allow installing unknown apps" — enable it once for your browser or file manager, which is the standard flow for installing outside the Play Store.

Import a subscription

Android clients generally support three import methods: pasting the link directly, scanning a QR code, or auto-detecting it from the clipboard. On the profiles page, create a new subscription, paste the link, save and update — a node group appearing in the list means it worked. Updates occasionally time out the first time on mobile data; switch to Wi-Fi and retry before assuming something's wrong.

How the VPN mode works and per-app proxying

The Android client takes over traffic through the system's VpnService API, no root needed. The first time you tap Connect, the system shows a "Connection request" authorization dialog — confirm it and a key icon appears in the status bar, meaning the virtual private network tunnel is up. This is equivalent to TUN mode on desktop: all app traffic is routed through Clash by default. For finer control, use "Per-app proxy": in allowlist mode only checked apps are proxied, while in exclude-list mode checked apps bypass the proxy entirely. It's a good idea to add banking and payment apps to the exclude list to avoid tripping their risk controls.

Keeping the app alive in the background

The most common issue on Android isn't configuration — it's the process getting killed: the proxy drops and the notification disappears after the screen has been locked a while. Three fixes: set the client to "Unrestricted" or add it to the battery optimization whitelist in system battery settings; on custom Android skins (MIUI, EMUI, ColorOS, etc.) also allow it in the autostart manager, and lock the app in the recent-apps view. Doing all three keeps the app running reliably on almost every phone.

5. iOS

Installing from the App Store

On iOS, Clash Plus is installed through the App Store — search for it, or jump directly from the store link on the iOS section of the download page. The app's official site is clashplus.io, and its update notes and feature documentation live there. iPhone and iPad share the same app with an adaptive interface.

Import a subscription and connect for the first time

Open the app, paste your link on the subscriptions page, and import — same as every other platform. The first time you tap Connect, iOS shows a system prompt asking to add a VPN configuration — this is the standard authorization flow for the NetworkExtension framework. Tap "Allow," verify with your passcode or Face ID once, and a matching VPN configuration will appear in system settings. From then on, connecting and disconnecting is a single tap inside the app, and you can also check the current status under Settings → VPN.

iOS-specific notes

• Config size. iOS gives the network extension process a limited memory budget, so subscriptions with an enormous node count or bulky rule sets may load slowly. If that happens, trim the subscription down or ask your provider for a lighter config, rather than repeatedly reinstalling.
• Network switching. The tunnel rebuilds automatically when switching between Wi-Fi and cellular, with a brief one-to-two-second interruption — this is normal.
• On-demand connection. The app can auto-connect on boot and whenever network access becomes available, relying on the system's on-demand rules — once enabled, you don't need to open the app manually each time.

6. Linux and servers

Installing on desktop distros

Clash Verge Rev is the top pick for desktop Linux; the Linux section of the download page provides both deb and rpm packages, and FlClash is a solid alternative. On Debian/Ubuntu, installing the local package with apt resolves dependencies automatically:

sudo apt install ./clash-verge-rev_amd64.deb

On Fedora-based systems, use sudo dnf install ./clash-verge-rev_x86_64.rpm. Launch it from your application menu once installed — subscription import works the same as on other desktop platforms.

System proxy and environment variables

Both GNOME and KDE have a graphical system proxy setting, which the client's "System Proxy" toggle writes into — browsers and most desktop apps will follow it. But a lot of Linux work happens in the terminal, and terminal programs read environment variables, not desktop settings. To route the current terminal session through the proxy temporarily:

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

For a permanent setup, add these lines to your shell's config file, or wrap them in an alias you can toggle on demand. Tools like git, curl, and wget all respect these variables; some tools (certain container runtimes, for example) have their own separate proxy settings that need configuring independently.

TUN permissions

Creating a TUN device on Linux requires the CAP_NET_ADMIN capability. Graphical clients usually provide an authorization button that escalates privileges via pkexec under the hood; if you're running the core binary directly, you can grant the capability once with setcap so you never need root to enable TUN afterward:

sudo setcap 'cap_net_admin,cap_net_bind_service=+ep' /usr/local/bin/mihomo

No desktop environment: running the mihomo core directly

On servers, routers, and NAS devices without a GUI, running the mihomo core directly is the standard approach — the core section of the download page has binaries for every architecture. The usual convention is to put your config at /etc/mihomo/config.yaml and the core binary at /usr/local/bin/mihomo, then write a systemd unit to keep it running:

[Unit]
Description=mihomo daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure

[Install]
WantedBy=multi-user.target

Save it as /etc/systemd/system/mihomo.service and enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo

Check status with systemctl status mihomo, and follow logs with journalctl -u mihomo -f. On first launch the core automatically downloads the GeoIP and GeoSite databases; if the server has no outbound internet access, you'll need to place those data files into the config directory manually, or rule matching won't work.

7. Verification and maintenance

Confirming the proxy is actually working

Don't just assume the proxy is on — cross-check with two pieces of evidence. First, visit any IP lookup site in your browser; if the exit IP shows the node's region, browser traffic is going through the proxy. Second, send a request directly to the proxy port from the command line and check whether you get a response header back:

curl -x http://127.0.0.1:7890 -I https://www.example.com

A status line like HTTP/2 200 confirms the proxy chain is working. The connections panel in desktop clients is also worth checking — it lists which rule and exit policy each live connection is hitting, the most direct way to answer "is this specific app actually going through the proxy." For a fuller first-run verification walkthrough, see Verifying Your First Connection.

Subscription updates and GeoIP data

Node info changes as providers make adjustments, so subscriptions need periodic updates — every client supports setting an auto-update interval, and once every 24 hours is generally enough. The other dataset worth maintaining is the GeoIP and GeoSite database, which entries like GEOIP,CN and GEOSITE depend on entirely; a stale database causes some domains and IPs to be misclassified, showing up as odd routing on specific sites. Client settings usually have an "Update GeoIP database" option — clicking it every few months is enough.

Logs and troubleshooting order

When something's wrong, temporarily bump the log level from info to debug — you'll get a lot more to work with. The recommended troubleshooting order goes three layers deep: first run a latency test on the node list to confirm the node itself works; then check the connections panel to confirm the target domain is hitting the rule you expect; only then suspect DNS — retry in a private browsing window to rule out local cache interference. Jumping around between these steps tends to turn simple problems into complicated ones. For how to read latency numbers and pick nodes, see the node selection guide.

8. Configuration FAQ

What the config file looks like

A Clash config is a YAML file — it's exactly what your subscription fetches. You don't need to write it by hand for everyday use, but understanding the key fields helps a lot when troubleshooting. A minimal skeleton looks like this:

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
    - 119.29.29.29

mixed-port is the local mixed proxy port; allow-lan controls whether other devices on your network can use this machine's proxy; mode corresponds to Rule/Global/Direct; the dns block controls domain resolution behavior. A subscription's config also includes three more major sections: proxies (nodes), proxy-groups (policy groups), and rules (routing rules).

YAML parsing errors

If the client reports "config parse failed" after you've edited it by hand, it's almost always a YAML formatting issue. Check three things: indentation must use spaces (two is the convention) — a stray tab breaks it immediately; there must be a space after the colon in a key name; and any value containing a colon, hash sign, or other special character needs to be wrapped in quotes. Backing up the original file before editing is the cheapest insurance you can buy.

Fake-IP-related issues

enhanced-mode: fake-ip in the config means DNS uses Fake-IP mode: the client returns a fake address from a reserved range first to speed up connection setup, while the real resolution happens over the proxy chain. It cuts down DNS leaks and speeds up the first packet, but a handful of scenarios that rely on the real IP — LAN device discovery, some game platform logins — will misbehave, and need those domains added to the fake-ip-filter list. For the underlying mechanics and a full list of affected scenarios, see Fake-IP Mode Explained.

Custom rules not taking effect

When adding your own routing rules on top of a subscription, remember one principle: rules match top to bottom, and the first match wins. If a custom entry sits after a broader catch-all rule, it will never get a chance to fire — specific domain rules need to come before catch-alls like GEOIP and MATCH. For rule syntax and ordering recommendations, see Rule Syntax and Priority Explained.

Subscription update failures

If clicking Update spins and then errors out, check four layers: whether your local network is working, whether the subscription link opens directly in a browser, whether the returned content is a valid config format, and whether the client is set to "update subscription via proxy" while disconnected. The full self-check list is written up here: Subscription Failure Troubleshooting Steps. For more scattered issues, the FAQ page keeps growing across four categories: basics, setup, usage tips, and troubleshooting.

This page is revised continuously as the client ecosystem changes. Always get installers from the download page; for your first setup, follow the getting started guide step by step.