The Complete Clash Setup Guide

This chapter covers three things: how the client and core divide the work, how to get a working subscription link ready, and the difference between system proxy and TUN mode. These concepts run through all five platform chapters, so a few minutes here will save a lot of repeated troubleshooting later.

Client vs. Core: Who Does What

What people call "Clash" is actually two layers: the core handles traffic forwarding, rule matching, and DNS, while the GUI client handles the interface, subscription management, and writing system settings. Most mainstream clients today run on the Mihomo core, and everything this guide covers — TUN, fake-ip, rule matching — is a core feature that the client simply exposes as a toggle. Once you get this, a few things make more sense: different clients behave almost identically under the hood, with differences mostly in UI and platform integration; client version and core version are two separate release tracks; and if one client seems to be "missing" a feature another has, it's usually just not exposed in the UI — the core almost certainly supports it.

You don't need to overthink client choice: Clash Plus is the top pick on every platform, with Clash Verge Rev recommended for Linux desktop. See the full list and installers on the download page, and a side-by-side comparison of interface, core, and maintenance status in Which Clash Client Should You Use?

Subscription Links: Treat Them Like Credentials

A subscription link is an HTTP(S) URL from your provider that the client fetches to pull down a full config with proxy nodes and rules. Two things to know: first, a subscription link is essentially your account credential — leaking it is the same as sharing your account, so never paste it anywhere public. Second, providers don't all output the same format; the common ones are Clash YAML and Base64, and compatibility and conversion are covered in Clash Subscription Formats Explained. Before importing, double-check you actually have a subscription link and not a single-node share link — the latter only describes one server and can't generate a full rule set.

System Proxy vs. TUN: Two Ways to Route Traffic

Across all platforms, there are only two ways to route your traffic. System proxy: the client opens a local listening port (commonly 7890) and writes "127.0.0.1:port" into your OS proxy settings; any app that respects the system proxy (browsers and most networked software) gets routed through it. It's lightweight, but command-line tools, some games, and certain system components bypass it. TUN mode: the core creates a virtual network adapter and intercepts all outbound traffic at the network layer, catching apps that ignore proxy settings entirely; the trade-off is it needs elevated access — a system service on Windows, a helper tool authorization on macOS, root or capability grants on Linux, and system VPN authorization on mobile.

One rule applies everywhere: never run system proxy and TUN at the same time. Stacking them causes traffic loops, DNS glitches, and other hard-to-pin-down issues — most of the "unexplainable" problems in Chapter 8 trace back to exactly this. If a term here is unfamiliar, check the Glossary anytime.

Pre-Install Checklist

• Confirm your OS meets the baseline: Windows 10 64-bit or later, macOS 11 or later are typical requirements; check the platform notes on the download page if you're on an older release.
• Have a working subscription link ready, and confirm it returns something when opened in a browser — a block of YAML text or a long encoded string both count as normal.
• Have administrator or root access on hand; both TUN mode and system service installation require it.
• Quit or uninstall any other proxy or "accelerator" software first — port and virtual adapter conflicts with these are the most common install-time issue.

Here's an overview of all five platforms — click any anchor to jump straight to that chapter:

Windows has the most moving parts of any platform: install blocking, system proxy configuration, TUN service installation, and UWP loopback restrictions each have their own hurdle. This chapter walks through them in order.

Download and Install

Get the installer from the Windows section of the download page. Clash Plus is the top pick, with Clash Verge Rev, FlClash, and Clash Nyanpasu as alternatives; Clash for Windows is no longer maintained and kept only as an archive — it's not recommended for new installs. The installer is an .exe — just double-click to run it. If a blue SmartScreen warning pops up, click "More info" then "Run anyway"; this is just Windows' standard warning for newly distributed installers, not a sign of a problem. Keep the default install path, or at minimum avoid paths with non-ASCII characters or spaces — some core components silently fail to parse config directories under such paths, and it's far cheaper to pick a clean path upfront than to debug it later. On first launch, Windows Firewall may prompt you — check "Private networks" and allow access.

Import Your Subscription

Open the client, go to the "Profiles" or "Subscriptions" tab, paste your subscription link, and click Import or Update. Success looks like a new entry in the profile list and proxy groups showing up on the "Proxies" tab. If import fails, first open the link directly in a browser to confirm it's reachable, then check the subscription troubleshooting section in Chapter 8. Once import succeeds, it's worth turning on auto-update with a 12–24 hour interval.

Turn On System Proxy

Toggle "System Proxy" on the client's main screen — under the hood, this just writes 127.0.0.1 plus the mixed port (usually 7890) into Windows' proxy settings. To verify, open Settings → Network & Internet → Proxy — "Use a proxy server" should be on with a matching address. Then visit a site outside China in your browser to confirm connectivity, and check an IP lookup site to confirm your exit IP has changed. One important note: turn off System Proxy before closing the client. Force-killing the process can leave the proxy setting stuck on, which shows up as no internet access at all after the client closes — if that happens, just turn it off manually in the system proxy settings.

Turn On TUN Mode

If you need command-line tools, games, or system components to also go through the proxy, switch to TUN mode instead. The first time you enable it, the client will ask to install a system service (this needs admin confirmation) — it runs the core with elevated privileges and creates a virtual network adapter. Once enabled, you'll see a new Mihomo / WinTun adapter under "Network Connections." Turn off System Proxy when you enable TUN — running both at once causes traffic loops or DNS issues. If the service fails to install, try running the client as administrator; if it keeps failing, uninstall any leftover service in the client settings and reinstall.

Platform-Specific Gotchas

• Port already in use: security software or dev tools often grab port 7890, which shows up as System Proxy being on but nothing working. See the port conflict section in Chapter 8 for how to find and change it.
• UWP loopback: Store apps block access to the local loopback address by default, so they don't go through the proxy. Some clients offer a "UWP loopback exemption" tool — check the box for the apps you need.
• Antivirus false positives: creating a virtual adapter and system service can trigger security software. Adding the install folder to your trusted list beforehand saves more hassle than approving alerts one by one.
• Leftover network adapters: after installing and removing different clients over time, you may end up with unused TAP / WinTun "ghost" adapters — remove them under "Network adapters" in Device Manager.
• Start on boot: enable this in the client's settings rather than dropping a shortcut into the startup folder — the built-in option brings up the system service in the right order too.

The macOS chapter comes down to two things: grabbing the installer for the right chip architecture, and getting through macOS's security prompts. These prompts only show up on first launch and after major updates — set them up once and you're done.

Choosing the Right Installer for Your Chip

macOS installers come in two builds: Apple Silicon (arm64) and Intel (x64). Click the Apple menu → "About This Mac" — if "Chip" shows an Apple M-series chip, grab arm64; if it shows Intel, grab x64. Installing the wrong architecture typically causes a crash on first launch, or noticeably worse performance under Rosetta emulation. Client choice is similar to Windows: Clash Plus is the top pick, with Clash Verge Rev and FlClash as alternatives; ClashX Meta is no longer maintained and kept only as an archive. Get the dmg from the macOS section of the download page, open it, and drag the app icon into your Applications folder to finish.

First Launch and Security Prompts

On first launch, macOS may warn that it "cannot verify the developer" or that the app is "from an unidentified developer." To fix this, open System Settings → Privacy & Security, scroll down to find the blocked app notice, and click "Open Anyway." You'll get a couple more prompts when the client writes system proxy settings or installs a helper service — just enter your password or confirm with Touch ID. These prompts only appear on first launch and after major version updates, not every time.

Importing a Subscription and Enabling System Proxy

Import works the same as on other platforms: paste your link on the Subscriptions tab → Update → check that proxy groups appear on the Proxies tab. After enabling "System Proxy," verify it under System Settings → Network → (your active connection) → Details → Proxies: both Web Proxy (HTTP) and Secure Web Proxy (HTTPS) should point to 127.0.0.1 and the client's port. Note that macOS saves proxy settings per network service (Wi-Fi, Ethernet, Thunderbolt Bridge) separately — if the proxy stops working after switching from Wi-Fi to Ethernet, just toggle System Proxy off and back on so the client writes the setting to the currently active connection.

Turn On TUN Mode

Enabling TUN on macOS requires the client to run the core with elevated permissions: the first time you turn it on, it'll ask to install a privileged helper tool or authorize a network extension — just confirm the prompt. Once it's working, running ifconfig in Terminal will show a new utun interface. As on Windows, only run one of TUN or System Proxy at a time. If you can't get online after enabling TUN, first check whether DNS settings are being overridden by an old config, and whether enterprise security software is blocking the network extension.

Platform-Specific Gotchas

• Leftover proxy setting: force-quitting the client (instead of quitting normally) can leave System Proxy stuck on, cutting off your internet. Turn it off manually in Network settings, or reopen the client and quit it normally.
• OS upgrades: major macOS upgrades can reset security authorizations — just go through the Privacy & Security prompt again on first launch; your config won't be affected.
• MDM-managed Macs: company-managed Macs may lock proxy and VPN settings via a configuration profile, which the client can't bypass — you'll need to contact your device administrator.
• Running multiple clients: installing several Clash-family clients side by side is fine, but only run one at a time — otherwise they'll fight over writing the system proxy settings.

Android has no separate system proxy toggle — clients always route traffic through the system VPN interface, which works the same way as TUN. This chapter is about getting the right build, granting the right permissions, and keeping the connection alive in the background.

Download and Choosing the Right ABI

Android installers are split by processor architecture (ABI): most phones from the last few years use arm64-v8a; older or budget devices may need armeabi-v7a; if you're not sure, grab the universal build — it's larger but works everywhere. Client order matches the download page: Clash Plus is the top pick, with Clash Meta for Android, FlClash, and Surfboard as alternatives, all available on the Android section of the download page.

Installing and Granting VPN Permission

During APK installation, Android may block it once with an "Install unknown apps" warning — go into Settings, allow it for whatever source you're installing from (browser or file manager), then go back and continue. The first time you tap Connect in the client, a "Connection request" dialog will appear — this is Android's VpnService permission prompt, and you need to allow it; once granted, a key icon appears in the status bar, meaning the tunnel is up. This permission is remembered per app, so you'll need to grant it again after uninstalling and reinstalling.

Import Your Subscription

Paste your link on the Profiles/Subscriptions page to import — some clients also support QR codes or auto-detecting a link from your clipboard. On mobile, it's worth turning on auto-update with roughly a 24-hour interval so node changes don't lag too far behind; common causes of update failures and fixes are covered in What to Do When a Clash Subscription Fails to Update.

Keeping the Connection Alive in the Background

Custom Android skins from Chinese manufacturers are notoriously aggressive about killing background processes — if your connection "drops after a while" or "disconnects after the screen's been locked," the OS has probably just killed the client. Three things to check: first, set the client to "Unrestricted" or "No optimization" in battery settings; second, allow it to auto-start and run in the background in your device's app management settings (naming varies by manufacturer); third, lock the client's card in the recent apps view. Doing all three gives you a real shot at staying connected long-term — doing just one still gets killed on some devices.

Platform-Specific Gotchas

• Private DNS conflicts: if the system's Private DNS (DoT) is set to a specific hostname, DNS queries may bypass the client and cause routing to behave oddly — switching it back to "Automatic" usually fixes this.
• VPN exclusivity: Android only allows one app to hold a VpnService connection at a time, so turning on Clash will disconnect other VPN-type apps, and vice versa — this is expected OS behavior, not a bug.
• Per-app proxy rules: most clients support an allow/exclude list by app; for network-sensitive apps like banking apps, add them to the exclude list to have them connect directly.
• Aggressive power saving: strict battery saver modes restrict background networking — turn it off for long idle sessions, or at least add the client to the exemption list.
• Behavior after reboot: on some systems, the VPN permission stays granted after a reboot but doesn't auto-reconnect — you'll need the client's "Connect on boot" option along with auto-start permission enabled together.

The iOS client is distributed through the App Store, making this the shortest setup process of any platform; the main things to watch are managing the VPN configuration and tunnel behavior after switching networks.

Getting the Client

Clash Plus is the top pick on iOS — search for it in the App Store, or jump straight to it from the iOS section of the download page. The official site is clashplus.io, where you can check platform support and feature details. The App Store build updates automatically, so there's no manual installer to download — which is also why this chapter skips the "choose your architecture" step.

Importing a Subscription and Connecting for the First Time

Open the client and go to the Subscriptions tab, then paste your link to import. A faster way on iOS: copy the link in Safari first, and the client will detect it in your clipboard on launch and ask if you want to import it — just confirm. The first time you tap Connect, a system dialog appears saying "'Clash Plus' Would Like to Add VPN Configurations" — tap Allow and confirm with Face ID, Touch ID, or your passcode; this is the standard authorization for iOS Network Extensions, and the configuration will show up under Settings → General → VPN & Device Management → VPN. Once connected, a VPN indicator appears in the status bar, meaning the tunnel is up.

Choosing a Mode and Switching Nodes

The iOS client offers the same three modes as other platforms — Rule, Global, and Direct — and Rule mode is fine for everyday use; the differences between all three are covered in Rule Mode vs. Global Mode vs. Direct Mode Explained. Switching nodes happens on the Proxies tab: run a latency test on your group first, then pick a node with low, stable numbers; switching nodes doesn't require reconnecting — the tunnel stays up while the core swaps the outbound connection internally.

How the System VPN Toggle Relates to the App

The VPN toggle in Settings and the Connect button in the client both control the same tunnel: turning VPN off from system Settings will show as disconnected in the client too. Deleting the VPN configuration (Settings → General → VPN & Device Management) is the same as revoking permission — the client will ask to add it again next time you connect. Multiple proxy apps each keep their own VPN configuration, and only one can be active at a time; one replacing another is expected system behavior, not a malfunction.

Platform-Specific Gotchas

• Reconnecting after network switches: the tunnel briefly rebuilds when switching between Wi-Fi and cellular, so a few seconds of dropped connectivity is normal; if it doesn't recover after a while, disconnect and reconnect manually.
• Low Data Mode: enabling Low Data Mode on cellular or Wi-Fi restricts background traffic, which can affect subscription auto-updates and tunnel stability — it's best to turn it off for networks you use regularly.
• On-demand connection: some clients offer "connect on demand" rules, where the OS automatically brings up the VPN during network activity; if the VPN toggle "won't stay off, keeps turning back on," disable on-demand connection in the client first, then disconnect.
• Regional App Store accounts: app visibility varies by App Store region — if you can't find it by search, use the store link from the download page instead.
• Power-saving effects: iOS Low Power Mode restricts background activity, so you may notice a brief delay on the first request after a long time locked — it clears up once you unlock the screen.

This chapter covers two tracks: desktop users installing a GUI client, similar to other platforms, and server/router users running the Mihomo core directly, managed via config files and systemd. Both are covered in full here.

Installing the Desktop Client

Clash Verge Rev is the recommended pick for Linux desktop, with FlClash as an alternative, both available from the Linux section of the download page. On Debian/Ubuntu-based distros, install the deb package with:

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

Use apt install ./filename instead of dpkg -i — the former resolves dependencies automatically. On Fedora-based distros, use the equivalent rpm package with dnf install. Once installed, launch it from your app menu — importing a subscription works the same as on other platforms: paste your link on the Subscriptions tab → Update → confirm proxy groups appear on the Proxies tab.

Three Ways to Route Traffic Through the Proxy

"System proxy" on Linux isn't a single switch — there are three common approaches, roughly in order of how much they cover. First, desktop environment proxy: GNOME and KDE have proxy settings in their network configuration, and this is exactly what a GUI client's "System Proxy" toggle writes to — it only affects desktop apps that respect it. Second, environment variables: terminals and most command-line tools read these variables:

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1

For one-off use, run these directly in your terminal; for something more permanent, add them to ~/.bashrc or ~/.zshrc. Keep in mind environment variables only affect processes started afterward — anything already running won't pick them up. Third, TUN mode: this covers all traffic, including programs that ignore environment variables entirely. Enabling TUN in a GUI client requires authorization — Clash Verge Rev will walk you through installing a privileged service; running the core manually requires root, or granting the binary network capabilities directly:

sudo setcap 'cap_net_admin,cap_net_bind_service=+ep' ./mihomo

Server Setup: Core + systemd

For headless servers, run the Mihomo core directly. Grab the archive for your architecture from the core section of the download page (amd64 for x86 servers, arm64 or armv7 for ARM devices depending on bitness), extract it into /usr/local/bin, and place your config at /etc/mihomo/config.yaml. Manage it with systemd:

[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 this as /etc/systemd/system/mihomo.service, then run:

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
journalctl -u mihomo -f

The last command tails the core's logs live — worth watching closely on first launch, since config syntax errors and port conflicts show up here directly. After editing your config, run systemctl restart mihomo to apply the change.

Platform-Specific Gotchas

• Distro differences: Arch-based distros can get a package from the AUR, but the version may lag behind the official installer — if something breaks, compare against the official package from the download page first to rule out packaging issues.
• Wayland tray icon: some Wayland desktops don't fully support tray icons, so closing the client window may leave you with no visible way back in — just relaunch it from your app menu to bring the main window back.
• DNS handling: if resolution acts up after enabling TUN, check whether systemd-resolved is conflicting with the core's DNS hijacking, and adjust the listener in the dns section of your config if needed.
• Firewall rules: on machines running firewalld or ufw, if other devices on your LAN need to use the proxy, open up the mixed port and set allow-lan: true in your config.
• Router hardware: for embedded architectures like MIPS, use the mips-softfloat core build; on resource-constrained devices, trim down your rule count to reduce memory usage.

Every client on every platform, in the end, is just driving the same YAML config. Once you understand its structure, you're no longer limited to "which button do I click" — you can see exactly what each toggle in the client actually changes. This chapter doesn't ask you to hand-write a config — your subscription already generates the whole thing — but it does help you read one.

Top-Level Structure Overview

A typical config's skeleton looks like this:

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

dns:
  enable: true
  enhanced-mode: fake-ip

proxies:
  - name: "Node A"
    type: vless
    server: example-server.com
    port: 443

proxy-groups:
  - name: "PROXY"
    type: select
    proxies: ["Node A", "Auto Select"]
  - name: "Auto Select"
    type: url-test
    proxies: ["Node A"]
    url: https://www.gstatic.com/generate_204
    interval: 300

rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

Six sections, each with its own job: the general fields set the port and running mode; the dns section controls domain resolution; proxies is the node list; proxy-groups organizes nodes into selectable groups; and rules decides which group each connection goes to. The "Proxies" tab in the client UI renders proxy-groups directly, and the mode switch changes the mode field.

Quick Reference: Common Fields

How Rules Get Matched

The rules list is checked top to bottom, and matching stops at the first hit — the MATCH entry at the end is the catch-all. Common rule types: DOMAIN-SUFFIX matches by domain suffix, DOMAIN-KEYWORD by keyword in the domain, GEOIP by the destination IP's country, and IP-CIDR by IP range. Once you get that matching is order-sensitive and stops at the first hit, a lot of routing confusion makes sense — if a site isn't going through the proxy as expected, it's usually matching an earlier rule first. The trade-offs between the three modes are covered in Rule Mode vs. Global Mode vs. Direct Mode Explained.

How Subscription Updates Actually Work

When you update a subscription, the client re-fetches the remote YAML and replaces your entire local config with it — which means any manual edits you made directly to the config file get overwritten on the next update. If you need long-term customizations (extra rules, a different port), use the client's override/merge feature (like Clash Verge Rev's Merge/Script tools) to keep your changes separate from the subscription itself, so they get reapplied automatically after every update. It's worth enabling auto-update everywhere, with a 12–24 hour interval; for update failures, see What to Do When a Clash Subscription Fails to Update, and for format compatibility issues, see Clash Subscription Formats Explained.

This chapter covers the most common issues shared across all five platforms, organized by symptom, each with a diagnosis path and fix. For more one-off Q&A, see the Help Center.

Subscription Import or Update Fails

Work through this in three steps. Step one: open the subscription link directly in a browser — if it won't load, the link has expired or your network is down; get a fresh link from your provider in the first case, or temporarily switch to a working node in Global mode and retry in the second. Step two: the browser opens it fine but the client throws an error — usually the provider is restricting access by User-Agent, or the returned format isn't compatible with your client; adjust the UA in the client's subscription settings for the former, or convert the format for the latter. Step three: import succeeds but the node list is empty — you may have a single-node share link instead of a subscription link, or the subscription is Base64-encoded while your client only reads YAML. The full diagnosis path is in this technical note.

Proxy Is On But You Have No Internet

Work outward from your device. Local layer: confirm System Proxy and TUN aren't both on, and that no other proxy software is running in the background; check the client's logs (or journalctl -u mihomo on Linux) for port conflict errors. Node layer: run a latency test on the Proxies tab — if everything times out, it's likely a subscription-wide issue or your connection to the server is down, so try a different group or contact your provider; if only a few nodes time out, just switch to a working one. Rule layer: if sites outside China work but a specific site doesn't, it's likely matching a rule you didn't expect — temporarily switch to Global mode to check; if that fixes it, you've confirmed it's a rule-matching issue.

Port Conflict

Symptoms: the client's logs show a bind/listen failure, or System Proxy is on but nothing works at all. On Windows, use netstat -ano | findstr 7890; on macOS/Linux, use lsof -i :7890 to find whatever's using the port — either quit that process, or change the mixed port to something free like 7891 in the client's settings. Note that the system proxy setting updates automatically to match a new port, but anything hardcoded to the old port in environment variables or third-party software needs to be updated manually.

DNS Poisoning and Resolution Issues

Symptoms: latency tests look fine but sites won't load, or domains resolve to obviously wrong addresses. Check things in this order: confirm the dns section in your config has enable: true and enhanced-mode: fake-ip; check whether another DNS component is intercepting resolution (Android Private DNS, systemd-resolved on Linux, a router's DNS cache); switch between TUN and System Proxy to see if the behavior changes, which tells you whether the issue is in resolution or forwarding. Under fake-ip mode, a handful of older apps don't handle virtual IPs well — you can exclude specific domains in the fake-ip-filter section of the dns config.

Slow Speeds

Break it down by layer before you start changing things: the node itself (is it slow on other devices too?), the network path (does it slow down predictably at peak hours, does switching protocol help?), and your local config (too many rules, DNS taking a roundabout path?). Testing methods and fixes for each layer are covered in detail in A Layer-by-Layer Guide to Diagnosing Slow Clash Speeds — no need to repeat it here. In practice, turning "it's slow" into actual latency and bandwidth numbers first, then deciding whether to switch nodes or adjust config, works far better than just randomly trying things.

Client Updates and Migrating Configs

Updating the client doesn't touch your subscription or config — they live in the user data directory, so an over-the-top install is safe. When switching clients or devices, don't bother exporting your old config — just re-import your subscription link on the new setup; it's the cleanest way, since the config is generated from the subscription and the link itself is a complete migration credential. The only thing you'd need to move by hand is local customizations outside the subscription, like override/merge scripts. The same applies when migrating away from an unmaintained client (like Clash for Windows) — see this client comparison for picking a new one, with installers always available on the download page.