Complete Clash Setup Guide for All Platforms

Chapter 1 · Before You Start: General Preparation

Regardless of platform, three things are the same everywhere: getting your subscription URL, understanding ports, and picking the right client. Get these three sorted first and every following chapter goes a lot smoother. As always: steps first, reasoning woven in as we go.

1.1 Get Your Subscription URL

A subscription URL (also called a subscription link) is a web address starting with https:// that the client checks periodically to pull down your node list and routing rules. Your provider issues it — you'll usually find it on the "Subscription" page of your provider's dashboard. If several formats are listed (Clash, Surge, Shadowrocket, etc.), pick the Clash or mihomo one.

Just two steps: log into your provider's dashboard and copy the subscription link, then paste it into the client's subscription field (see each platform's chapter below for where that field lives). The link usually includes a token parameter — whoever has this link can use your plan, so treat it like a password.

1.2 Know Your Ports

Clash intercepts traffic by opening a few ports on 127.0.0.1, so the system or individual apps can send traffic there for the core to route according to your rules. That makes "ports" the first concept worth understanding after installation. Common defaults (these vary by client — always check your own settings page):

First thing to do after installing: open the client's settings page, find "Port," and note the actual port number in use. You'll need this number whether you're manually configuring a proxy for some app or troubleshooting a "port in use" error. The "system proxy" toggle, at its core, just writes 127.0.0.1 plus this port into your OS's proxy settings.

1.3 Pick the Right Client

The client lineup is identical across all five platforms and matches the download page exactly: Clash Plus is recommended everywhere, with alternatives per platform; discontinued legacy clients are kept for reference only. If you're unsure which to pick, check the conclusions on the Client Comparison page first; once decided, grab the right build from the Download page using the entries below:

Chapter 2 · Windows Setup

2.1 Download and Install

Steps: Open the Windows section of the Download page, and the first card is the recommended Clash Plus — click "Download Installer" to get the .exe file. Requires Windows 10 or later, 64-bit. Double-click to run, follow the wizard, and leave the default install path as-is.

On first launch, Windows Security might ask whether to allow the app network access on private and public networks — check both boxes and allow it. The client needs to reach the internet to fetch your subscription and needs to open local ports, and blocking either breaks the whole setup.

2.2 Import Your Subscription

1. Open subscription managementIn Clash Plus, it's "Subscriptions" on the left sidebar; in Clash Verge Rev, also "Subscriptions," then click "New."
2. Paste your subscription linkGive it a name you'll recognize (e.g., your provider's name), paste the link you copied in Chapter 1 into the URL field, and save.
3. Update the subscriptionClick the refresh button on the subscription card — the client fetches nodes and rules, and seeing nodes appear in the list means it worked. While you're at it, set the auto-update interval to 24 hours.
4. Pick a node and test latencyGo to the "Proxies" tab, pick a node from a proxy group, and click the lightning icon to test latency. Favor nodes with consistently low latency across multiple tests; the "Auto" group picks automatically by latency, which is fine for beginners.

2.3 Turn On System Proxy

Steps: Find the "System Proxy" toggle on the main screen and turn it on — that's it. Why it works: flipping the switch writes an address like 127.0.0.1:7897 into Windows's proxy settings (Settings → Network & Internet → Proxy), and any app that respects the system proxy — Edge, Chrome, and most productivity software — automatically routes through Clash.

To verify: open a site that shows your public IP in a browser — if the location matches your node, the connection is working. For a more thorough check (latency testing, catching "false positives"), see the blog's first-connection verification guide.

2.4 TUN Mode (Virtual Network Adapter)

System proxy has one blind spot: apps that ignore OS proxy settings (some games, command-line tools, UWP apps) won't be routed through it. TUN mode works by creating a virtual network adapter that pulls all system traffic in at the network layer, regardless of whether the app cooperates.

Steps: Turn on "TUN Mode / Virtual Adapter" in settings. The first time, you'll be prompted to install a network adapter driver and run the client as administrator — just follow the prompts to authorize. After that, all system traffic routes through Clash.

2.5 Windows-Specific Pitfalls

• UWP apps can't connect.Windows Store apps (UWP) are blocked from accessing 127.0.0.1 by default, so system proxy doesn't reach them. Most clients include a "UWP Loopback Unlock" tool — check the box for the target app to lift the restriction, or just switch on TUN mode to bypass this entirely.
• Port already in use.If startup fails with a port-in-use or bind error, something else has claimed that port. Two commands to find the culprit:

netstat -ano | findstr :7897
tasklist | findstr "PID"

Either close the offending process, or change the port in settings to something free (like 7899) — the system proxy will follow the new port automatically. See Chapter 8 for the full troubleshooting order.

• Doesn't start on boot.Check "Launch on Startup" in settings, and "Silent Start / Minimize to Tray" if you want it, so the proxy is ready right after boot without a manual launch.

Chapter 3 · macOS Setup

3.1 Download and Install

Head to the macOS section of the Download page: Clash Plus is recommended, with Clash Verge Rev and FlClash as alternatives; ClashX Meta is discontinued and kept for reference only — don't install it on a new machine. Before downloading, check your chip: click the Apple menu → "About This Mac" — if it lists an Apple M-series chip, grab the arm64 build; for Intel, grab the x64 build. Picking the wrong one means it simply won't launch.

Installing: you'll get a .dmg — double-click to mount it, then drag the app into the "Applications" folder. If the first launch says "cannot verify developer," go to System Settings → Privacy & Security, find the relevant prompt, and click "Open Anyway." This is macOS's standard gatekeeping for non-App-Store apps, not a sign of a problem.

3.2 Import Subscription and Enable System Proxy

Import: open the client and find subscription management (in the Verge family, it's the "Subscriptions" tab; in the ClashX family, it's the menu bar icon → "Config" → "Remote Config" → "Manage"). Add a remote config, paste your subscription link, and update. Once nodes appear, go to the proxies tab, pick one, and test latency — same logic as Windows.

Turning on system proxy: check "Set as System Proxy." Same principle as Windows — the client points macOS's Web Proxy (HTTP) and Secure Web Proxy (HTTPS) settings to 127.0.0.1 plus a port. You can confirm this at System Settings → Network → Details → Proxies; unchecking the box tells the client to clean it up.

3.3 Enhanced Mode and TUN

Naming varies across macOS clients: the ClashX family calls it "Enhanced Mode," the Verge family calls it "TUN Mode" — both are the same virtual-adapter, system-wide takeover. Turning it on for the first time will ask you to install a helper tool and enter your login password to authorize; after that it behaves just like TUN on Windows. Stick with system proxy day-to-day, and only turn this on for apps that won't respect the proxy.

3.4 macOS-Specific Pitfalls

• Lots of password prompts.Installing the helper tool and changing system proxy settings both trigger authorization prompts — this is expected; just enter your login password.
• Can't find the menu bar icon.On notch-screen models, menu bar space is tight and the icon can get pushed off; quit a few less-used menu bar apps, or use a menu bar management tool to rearrange things.
• Proxy breaks after sleep/wake.Occasionally the system proxy state gets lost after sleep — toggle the system proxy switch off and back on, or restart the client, to fix it.
• Terminal doesn't use the system proxy.macOS's system proxy only covers GUI apps — command-line tools like git, curl, and brew need to be pointed at the proxy manually. For a one-off session:

export http_proxy=http://127.0.0.1:7897
export https_proxy=http://127.0.0.1:7897
export all_proxy=socks5://127.0.0.1:7891

Add this to ~/.zshrc to make it permanent; use your client's actual port from its settings page.

Chapter 4 · Android Setup

4.1 Download and Install

Head to the Android section of the Download page: Clash Plus is recommended, with Clash Meta for Android, FlClash, and Surfboard as alternatives. After downloading the APK, tap to open it — Android will warn "Install unknown apps is disabled." Follow the prompt to Settings and grant permission just for the browser or file manager you're using, not a system-wide "allow all sources" toggle.

Choosing the build: most phones from the last few years are arm64 — go with that. If installation fails or the app crashes on an older device, try the arm or universal build instead.

4.2 Import Subscription and Connect

Steps: open the client, go to the "Profiles" tab, tap the plus icon and choose "Import from URL," paste your subscription link, save, and select this profile. Back on the main screen, tap the connect button — Android shows a "Connection Request" dialog asking to set up a VPN connection; tap OK.

Why: Android doesn't let regular apps modify system proxy settings directly, so Clash on Android always works through the system's VPNService API — the OS hands all traffic to the client, which functions much like TUN mode on desktop. Once connected, a key icon appears in the status bar with a persistent notification; tap "Stop" in that notification to disconnect.

4.3 Per-App Proxy and Keeping It Alive in the Background

Per-app proxy.Under "Access Control / Per-App Proxy," choose which apps go through the proxy and which connect directly. A common setup is to let local apps connect directly and route everything else through the proxy — this saves node bandwidth and avoids triggering fraud checks on banking apps.

Keeping it alive in the background.This one's Android-specific homework: many manufacturer skins aggressively kill background processes, which shows up as "disconnects after the screen's been off a while." Three fixes: disable battery optimization for the client in system settings; allow it to auto-start in your autostart manager; and lock its card in the recent-apps view.

Private DNS.If "Private DNS" is enabled in system settings and pointed at an unreachable server, it can conflict with the proxy's DNS resolution — nodes work fine but pages won't load. Set it to "Off" or "Automatic" to fix this.

Chapter 5 · iOS Setup

5.1 Install from the App Store

Clash Plus is the recommended client on iOS, installed directly from the App Store: open the iOS section of the Download page and tap the store link, or search for it in the App Store. The official client site is clashplus.io — check there for changelogs and usage announcements.

Worth noting: all proxy clients on iOS work as system "Network Extensions," so you'll be asked to add a VPN configuration the first time you launch. That's standard behavior for every app in this category, not an extra permission grab from any one app.

5.2 Import Subscription and Connect

Steps: open Clash Plus, go to the Profiles/Subscriptions tab, add a subscription, paste your link, and update to fetch nodes. Back on the home screen, pick a node from a proxy group and flip the connect switch at the top. On first connection, iOS shows an "Add VPN Configuration" prompt — tap Allow and confirm with Face ID or your passcode. A VPN icon in the status bar means you're connected.

It's worth turning on "On Demand": it auto-reconnects when switching between Wi-Fi and cellular or waking from lock screen, so you're not toggling it manually all the time.

5.3 iOS-Specific Pitfalls

• VPN configs override each other.iOS only allows one VPN configuration to be active at a time. If you have multiple proxy apps installed, turning one on disconnects the other; if things aren't connecting, check Settings → General → VPN & Device Management to see which one is currently active.
• Brief drops when switching networks.The connection rebuilds momentarily when switching between Wi-Fi and cellular — this is normal and resolves itself within a few seconds without needing to toggle anything.
• Background App Refresh.Allow "Background App Refresh" for the client in system settings to keep long-lived connections more stable.

Chapter 6 · Linux Setup

Linux setup splits into two paths: desktop environments use a GUI client, while servers and routers run the mihomo core directly. This chapter covers desktop first, then server setups.

6.1 Desktop GUI Client

The Linux section of the Download page recommends Clash Verge Rev (available as .deb and .rpm), with FlClash (.deb) as an alternative. Pick the package for your distro: .deb for Debian, Ubuntu, and derivatives; .rpm for Fedora, openSUSE, and similar.

Installing on Debian-based systems (match the filename to what you actually downloaded):

sudo dpkg -i clash-verge-rev_amd64.deb
sudo apt -f install

The second line matters because dpkg alone doesn't resolve dependencies — apt fills in the gaps if you hit a dependency error. On Fedora-based systems:

sudo dnf install ./clash-verge-rev.x86_64.rpm

6.2 Import Subscription and System Proxy

Subscription import works the same as on desktop: add the link on the subscriptions page, update, pick a node, test latency — no need to repeat that here.

On GNOME, the system proxy toggle writes to Settings → Network → Network Proxy; but on KDE, tiling window managers, or minimal desktop environments, it may not write anywhere at all. Two fallback options: manually set HTTP, HTTPS, and SOCKS proxies to 127.0.0.1 and the matching port in your desktop's network settings; or set shell environment variables, which work directly for command-line tools:

export http_proxy=http://127.0.0.1:7897
export https_proxy=http://127.0.0.1:7897
export all_proxy=socks5://127.0.0.1:7891

Add this to ~/.bashrc or ~/.zshrc to make it permanent. GUI apps use the system proxy, command-line tools use the environment variables — the two don't interfere with each other.

6.3 Server Setups: Running the mihomo Core Directly

Headless servers and routers run the core directly. On the download page's "Core" section, grab the build matching your architecture: amd64 for x86 servers, arm64 or armv7 for Raspberry Pi and ARM boxes. Four steps:

1. Place the binaryExtract the downloaded archive, move mihomo to /usr/local/bin/, and make it executable (chmod +x).
2. Set up a config directoryCreate /etc/mihomo and save your subscription content as config.yaml:

sudo mkdir -p /etc/mihomo
curl -L "https://example.com/sub?token=xxxx" -o /tmp/config.yaml
sudo mv /tmp/config.yaml /etc/mihomo/config.yaml

The example link is a placeholder — swap in your own subscription link. The Clash subscription your provider gives you is already a complete mihomo config.

1. Check the key settingsOpen config.yaml and confirm these match what you expect:

mixed-port: 7897        # Local proxy entry point
allow-lan: false        # Whether to allow LAN devices to connect
mode: rule              # Rule mode
log-level: info
external-controller: 127.0.0.1:9090   # Management API, bound to localhost only

1. Manage it with systemdCreate /etc/systemd/system/mihomo.service:

[Unit]
Description=mihomo proxy service
After=network-online.target
Wants=network-online.target

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

[Install]
WantedBy=multi-user.target

Then enable it and follow the logs:

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

To update your subscription later, re-run the curl command from Step 2, then systemctl restart mihomo. To automate this, add a crontab entry that pulls once a day.

6.4 Linux-Specific Pitfalls

• Wrong architecture.Running an amd64 binary on ARM fails immediately with "Exec format error." Run uname -m first to check your architecture (x86_64, aarch64, armv7l) before picking a build.
• LAN sharing is off by default.allow-lan defaults to false; set it to true to share with other devices on your network, open the port in your firewall, and only do this on networks you trust.
• Don't expose the management API.external-controller should always bind to 127.0.0.1; binding to 0.0.0.0 without setting a secret hands control of your proxy to anyone who can reach it.
• GeoIP / GeoSite databases.The core relies on these two databases for routing decisions; GUI clients typically update them automatically. For manual updates and custom sources, see the blog's GeoIP and GeoSite guide.

Chapter 7 · System Proxy, TUN, and Rule-Based Routing

"System proxy" and "TUN" have come up repeatedly in earlier chapters — this chapter lines up all three routing methods side by side, then explains how rule-based routing decides where traffic goes once it reaches Clash. Understanding the mechanics tells you exactly where to look when troubleshooting.

7.1 Comparing the Three Routing Methods

The rule of thumb: use system proxy if it works, skip TUN if you can, and configure a single app manually rather than touching global settings if that's all you need. The smaller the scope, the smaller the surface area when something breaks — which is why every earlier chapter covers system proxy before TUN.

7.2 How Rule Matching Order Works

Once traffic reaches Clash, it's checked against the rules list from top to bottom: the first match wins and dictates the routing policy, and nothing further down gets checked. If nothing matches, it falls through to the final MATCH rule. A typical setup looks like this:

rules:
  - GEOSITE,private,DIRECT      # Private addresses go direct
  - GEOIP,CN,DIRECT             # Mainland China IPs go direct
  - GEOSITE,gfw,PROXY           # Blocked sites go through the proxy
  - MATCH,PROXY                 # Everything else goes through the proxy

The order itself is the strategy: direct rules first, proxy rules after, MATCH always last. GEOSITE matches against a domain database, GEOIP matches by IP location — see the dedicated blog post for how to update both. DIRECT means connect directly, PROXY hands traffic to the selected node, and REJECT blocks it outright (commonly used for ad-blocking rules).

The "Rule / Global / Direct" modes in the client UI act as an overall switch for this whole system: Rule mode follows the list above, Global mode ignores rules entirely and routes everything through the selected node, and Direct mode sends everything DIRECT. For the full comparison on which to pick, see the proxy modes guide — not covered further here.

7.3 Proxy Groups: A Layer Between Rules and Nodes

When a rule matches, it usually points to a "proxy group" rather than a specific node. A proxy group bundles several nodes together and decides how to pick among them: select means manual selection — whatever you click on the home screen is what's used; url-test automatically tests latency and always uses the fastest node; fallback checks availability in order and switches to the next node if the first one drops. The "Auto" and "Failover" groups commonly seen in subscriptions are just friendlier names for the latter two.

Understanding this layer explains a lot of behavior: why you can pick nodes from the home screen (a select group waiting for your input), and why your route sometimes changes without you touching anything (a url-test group switching automatically based on speed tests). To troubleshoot "wrong node" issues, check the logs to see which group a rule matched, then check the home screen to see what that group currently has selected — that narrows it down in two steps.

Chapter 8 · FAQ

Sorted by how often each comes up, written as "symptom → what to check, in order." For deeper log-based diagnosis, see the log troubleshooting guide; common beginner questions are also rounded up in Top 10 Beginner Questions.

8.1 Subscription Update Fails

Symptom: clicking update shows a failure, timeout, or "unable to parse" error. What to check, in order: ① Paste the subscription link directly into a browser address bar — if it doesn't return any text, the link is dead or your provider is having issues, so reset it from their dashboard; ② Switch to mobile data and try updating once more to rule out local network interference with the subscription domain; ③ Check that your system clock is accurate — a large time offset breaks HTTPS certificate validation; ④ Toggle "Update via proxy / Update directly" in client settings and try again; ⑤ If none of that works, check the client logs for the actual error and match it against the log troubleshooting guide.

8.2 Port Already in Use

Symptom: startup fails with "port in use" or a bind error. Use netstat from Chapter 2 on Windows; on macOS and Linux use:

lsof -i :7897

Once you've found the offending process, either close it or change the port in client settings to something free (7899 or 17890 both work). After changing it, toggle system proxy off and back on so your OS points to the new port.

8.3 System Proxy Is On, But the Browser Isn't Using It

First check for proxy-switching browser extensions — these override system settings and take priority whenever active. Then check the browser's own proxy setting: Firefox defaults to "Use system proxy settings," but switching it to "Manual" makes it independent. Command-line tools were never covered by system proxy in the first place — set them up separately using the environment-variable method from the macOS or Linux chapter.

8.4 Doesn't Launch on Boot

After checking "Launch on Startup" in client settings, confirm on Windows via Task Manager → Startup that the entry shows "Enabled"; on macOS, check System Settings → General → Login Items. If it's checked but still won't auto-launch, security software is likely blocking the startup entry — add the client to its allowlist.

8.5 Sharing the Proxy with Other Devices on Your LAN

Steps: turn on "Allow LAN Connections (allow-lan)" in client settings, find this machine's LAN IP (ipconfig on Windows, ip addr on macOS/Linux), and set other devices' proxy to this machine's IP plus the port. Two things to watch for: open the port in your firewall, and only do this on trusted networks like your home — enabling it on public Wi-Fi shares your proxy with everyone else on that network.

8.6 Broke the Config File, Client Won't Start

If the client fails to launch or shows a blank screen after manually editing the config, it's almost always a YAML syntax error: indentation must use spaces, not tabs, and colons need a space after them. Fix: use the client's built-in "Restore Default Config" option, or re-import your subscription to overwrite it. To keep your edits, check the error line number and fix it line by line. Keeping a backup before editing configs is the cheapest insurance you'll ever buy.

8.7 Where to Find the Logs

Every client has a "Logs" tab, filterable by info, warning, and error level. The standard troubleshooting move: reproduce the issue → check the last few log lines immediately → search the error keywords against the table in the log troubleshooting guide. Config syntax errors, subscription parsing failures, and port conflicts account for the vast majority of beginner errors.

8.8 Nodes Work Fine, But a Few Sites Won't Load

Symptom: most sites load fine, but a handful just keep spinning. This is usually a routing issue, not a node problem. What to check, in order: ① Open the client logs and visit the site again — see which rule the domain matched and which group it was sent to. If it was sent DIRECT, the rule database doesn't cover that domain, so add a manual domain rule pointing it to the proxy; ② Switch to Global mode and try again — if it loads, that confirms it's a routing issue, and you can fix it with ①; if it still doesn't load in Global mode, try a different node; ③ Some sites are sensitive to IP location, so switching to a node in a different region often fixes it right away.

For terms this page doesn't cover — subscription, node, proxy group, mixed port, and so on — check the Glossary. If you're new and want the fastest path to a working setup, go back to the Setup Guide and follow the three-step walkthrough, then return here for platform-specific details.