Clash Setup Across All Platforms: A Five-Platform Reference Handbook

CH-00 · General Preparation: Three Things to Gather Before You Start

Every platform's setup process rests on three prerequisites: an installer that matches your device, a valid subscription link, and a basic understanding of how the client, core, and config relate to each other. Missing any one of the three will stall you somewhere down the line, so work through this chapter before jumping into a platform section.

How the Client, Core, and Config Relate

What people casually call the "Clash client" is a graphical shell wrapping a core program that actually handles traffic (most mainstream clients now bundle the Mihomo core). The client handles the interface — importing subscriptions, switching nodes, toggling the system proxy; the core establishes proxy connections, matches rules, and forwards traffic according to a config file. The config file (a Profile) is a YAML document containing nodes, proxy groups, and rules, usually generated automatically from a subscription link rather than written by hand. Once you understand this layering, troubleshooting becomes much clearer: interface glitches point to the client, connection issues point to the config and nodes, and rules that don't fire point to the rules section of the config.

Getting and Safeguarding Your Subscription Link

The subscription link is issued by your proxy service provider, usually available in their user dashboard behind a "copy subscription" button, and comes out as a full https address. Paste this address when importing into a client, and the client will periodically pull the latest nodes and rules from it. Two rules for handling it: first, the subscription link embeds an identity token equivalent to account credentials — never paste it into chat groups or leave it visible in screenshots; second, if the link has expired or lapsed, the client will fail to update — in that case, go back to the provider's dashboard and re-copy the link rather than assuming the client is broken. The full diagnostic order for subscription failures is covered in Subscription Link Failure Checklist.

Platform-to-Client Mapping

Available clients differ by platform. The table below summarizes the lineup on this site's download page; the top pick on every platform is Clash Plus (distributed via the App Store on iOS, as an installer elsewhere):

The discontinued Clash for Windows and ClashX Meta remain available as archived downloads for existing users, but they're not recommended for new installs — core and protocol support for them won't be updated going forward.

↑ Back to table of contents

CH-01 · Windows: Installation, Service Mode, and UWP Loopback

Download and Install

Head to the download page's Windows tab to get the installer. Clash Plus is the top pick, with Clash Verge Rev, FlClash, and Clash Nyanpasu as alternatives — all x64 .exe installers compatible with Windows 10 and Windows 11. Double-click the installer and keep the default install path (avoid custom paths with Chinese characters or spaces, since some components are sensitive to that). The first time you run a freshly downloaded installer, SmartScreen may show a "Windows protected your PC" prompt — this is a generic block for low-download-count files: click "More info," then "Run anyway" to continue. On first launch after installation, the system firewall will ask for network access permission — check "Private networks" and allow it.

Import a Subscription

Open the client, go to the Profiles page, paste the subscription link into the address field, and click Import/Download. The client fetches the config and generates a profile card — click it to set it as active. Then go to the Proxies page and confirm the node list has loaded — an empty list means the subscription fetch failed; check the error table in Chapter 7 of this page.

System Proxy and TUN Mode

Windows offers two ways to take over traffic. Option one is the system proxy: turn on the "System Proxy" switch on the client's home screen — this rewrites Windows Internet settings so that apps that respect them (browsers, most desktop software) send traffic to the client's local listening port (7890 by default). Option two is TUN mode: the client creates a virtual network adapter and takes over all outbound traffic at the network layer, including command-line tools and game clients that ignore the system proxy setting. Before turning on TUN, install Service Mode in Settings first — a UAC prompt will appear; approve it and the service stays resident, after which you can flip the TUN switch. Don't rely on both at once: use the system proxy for everyday use, and switch to TUN only when a specific program won't route through the proxy.

Platform-Specific Issues

UWP loopback restriction. UWP apps distributed through the Microsoft Store are blocked by default from accessing the local loopback address (127.0.0.1), so Store apps may bypass the proxy entirely under system proxy mode. Some clients include a "UWP loopback exemption" tool in Settings for one-click fixes; you can also manually exempt a single app with the built-in command, for example to exempt the Store app itself:

CheckNetIsolation.exe LoopbackExempt -a -n="Microsoft.WindowsStore_8wekyb3d8bbwe"

If you'd rather not handle apps one by one, switch to TUN mode instead — network-layer takeover isn't affected by the loopback restriction.

Port conflicts. A port error on client startup usually means port 7890 is already in use by another program (or a leftover client process that didn't fully exit). Use the following command to find the PID of the process holding the port, then end it in Task Manager:

netstat -ano | findstr "7890"

Launch at startup. Enable launch-at-startup and silent start in the client's settings so the proxy is ready as soon as the system boots; if you also use TUN, Service Mode needs to already be installed, otherwise TUN won't kick in automatically after autostart.

↑ Back to table of contents

CH-02 · macOS: Chip Architecture, Security Prompts, and Enhanced Mode

Confirm Your Chip Architecture First

macOS installers come in Apple Silicon (M-series, arm64) and Intel (x64) builds — picking the wrong one means the app won't launch or runs through inefficient translation. To check: click the Apple menu in the top-left corner → "About This Mac." If the chip line shows "Apple M…," pick the Apple Silicon build; if it shows "Intel…," pick the Intel build. Then head to the download page's macOS tab and grab the matching .dmg file — Clash Plus is the top pick, with Clash Verge Rev and FlClash as alternatives.

Install and First Launch

Double-click the .dmg to mount the disk image, drag the app icon into Applications, then eject the image. The first time you open an app downloaded from the internet, Gatekeeper shows a confirmation dialog — click "Open." If you see "can't be opened because the developer cannot be verified," right-click the app icon → Open, and confirm again. If you see "file is damaged and can't be opened, move it to the Trash," that's the quarantine attribute triggering the block, not actual file damage — remove the quarantine flag in Terminal and reopen (adjust the path to match your app's actual name):

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

Import a Subscription

The flow matches Windows: paste the subscription link on the config page → import → enable the generated profile → confirm the node list isn't empty on the Proxies page. The macOS client usually lives in the menu bar; if you close the main window, reopen it from the menu bar icon.

System Proxy and TUN (Enhanced Mode)

Turning on "System Proxy" requires the client to modify macOS network preferences — the first time, it will ask you to install a helper and enter your admin password, a one-time authorization. Once enabled, you can confirm under System Settings → Network → current network → Details → Proxies that the HTTP/HTTPS proxy points to the local port. TUN mode (some clients call it "Enhanced Mode") creates a virtual network interface that takes over all traffic and also requires admin authorization the first time; whenever the system asks to confirm a network extension or allow a background item, always allow it — otherwise the virtual adapter won't come up.

Platform-Specific Issues

Terminal doesn't use the system proxy. Command-line tools don't read the system proxy setting by default; export the environment variables manually in your terminal session (match the port to what the client is actually listening on):

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890

Launch at startup. Go to System Settings → General → Login Items and add the client to "Open at Login"; the client's own autostart toggle does the same thing, so pick one — adding both launches two instances.

ClashX Meta users. This client is no longer maintained and remains on the download page as an archive. Existing configs still work, but we recommend migrating to Clash Plus or Clash Verge Rev following the steps above — just re-import your subscription.

↑ Back to table of contents

CH-03 · Android: Picking an ABI Package, VPN Authorization, and Background Persistence

Pick an Installer by ABI Architecture

Android installers are split by CPU instruction set (ABI); picking the wrong one causes install failures or a non-functioning app. Reference table:

Get the installer from the download page's Android tab — Clash Plus is the top pick, with Clash Meta for Android, FlClash, and Surfboard as alternatives. If you're not sure of your device's architecture, just go with the universal build.

Install and Authorize

After downloading the .apk from your browser, tap to install — the system will show "Install unknown apps not allowed." Follow the prompt into Settings, turn on "Allow app installs from this source" for your current browser (or file manager), then go back and continue installing. This is Android's standard flow for sideloaded apps, and you only need to authorize each source once.

Import a Subscription

Open the client, go to the config page, tap New Profile → choose "URL / Subscription Link" → paste the link → save. The client fetches the remote config and generates a profile entry — select it to enable. Some clients can detect a subscription link directly from the clipboard; after copying one, opening the app will show an import prompt.

Starting the Proxy: VpnService Takeover

Android has no desktop-style "system proxy switch"; instead, the client builds a local VPN tunnel through the system's VpnService interface to take over traffic, functionally equivalent to TUN mode on desktop. The first time you tap the start button, the system shows a "Connection request" dialog — confirm it, and a key icon appears in the status bar once the proxy is active. The "Access Control" setting in the client lets you specify which apps route through the proxy and which connect directly, for per-app proxy configuration.

Platform-Specific Issues

Killed in the background. Battery-saving policies on customized Android skins may clear resident background processes, causing the proxy to disconnect periodically on its own. Fix: set the client to "No restrictions" or add it to the allowlist in your system's battery/background management settings, and lock it in the recent apps view; the exact menu names differ by manufacturer, but look for battery optimization and autostart management.

Private DNS conflicts. If "Private DNS" in system settings points to an encrypted DNS provider, it can interfere with the client's DNS takeover (especially fake-ip mode), causing some domains to resolve incorrectly. Set Private DNS to "Automatic" or turn it off while using the proxy.

A node is selected but some apps still bypass the proxy. First check whether the Access Control list excludes that app, then confirm the app doesn't have its own built-in proxy-bypass logic.

↑ Back to table of contents

CH-04 · iOS: App Store Install and VPN Configuration Authorization

Get the Client

iOS is served through the App Store, with Clash Plus as the client — see the store link on the download page's iOS tab; the developer's official site, clashplus.io, is the primary source for verifying app details. Search the App Store or jump straight to the listing from the download page, then install as you would any normal app; it works on both iPhone and iPad.

First Launch: Allow the VPN Configuration

Proxy takeover on iOS runs through the system's network extension framework. The first time you connect in the client, the system shows a "'Clash Plus' Wants to Add VPN Configurations" confirmation dialog — this step is mandatory. Tap "Allow" and verify with your passcode or Face ID as prompted. After authorization, System Settings → General → VPN & Device Management will show a matching entry, its status synced with the client's own connection toggle — either place will tell you whether you're currently connected.

Import a Subscription

Open the client's config page, choose to add via URL, paste the subscription link, and save — the client fetches and generates a profile, which you then select to enable. If you've already copied the subscription link in Safari or another app, returning to the client usually triggers a clipboard import prompt — just confirm it. After importing, check the node list has loaded, then go back to the main screen and flip on the connection switch.

Usage Notes and Common Issues

Switching configs or nodes. The client automatically rebuilds the connection after you switch profiles or nodes; the VPN icon in the status bar briefly disappearing and reappearing is normal — no manual reconnect needed.

Brief drops when switching networks. Moving between Wi-Fi and cellular requires the network extension to rebuild the tunnel, causing a few seconds of unavailability that resolves on its own; if it doesn't recover after a while, manually toggle the connection switch off and back on in the client.

Low Data Mode alongside VPN. The system's Low Data Mode can restrict background traffic, delaying automatic subscription updates — trigger important updates manually while the client is in the foreground.

Subscription update failures. Same logic as other platforms: first confirm the subscription link itself is still valid (see the error table in Chapter 7 and the Subscription Failure Checklist), then check whether the current network can reach the subscription address directly.

↑ Back to table of contents

CH-05 · Linux: Desktop Client, Environment Variables, and Running the Core Directly

Choosing and Installing a Client

Clash Verge Rev is the recommended Linux desktop client, with FlClash as an alternative. The download page's Linux tab offers both .deb (Debian/Ubuntu family) and .rpm (Fedora/RHEL family) packages — pick the one matching your distro. In a graphical environment, double-click to hand it to your software center, or install via the package manager in a terminal (filenames depend on what you actually downloaded):

# Debian / Ubuntu family
sudo apt install ./clash-verge-rev_amd64.deb

# Fedora / RHEL family
sudo dnf install ./clash-verge-rev_x86_64.rpm

Installing through a package manager auto-resolves dependencies and gives more readable errors on failure. Once installed, launch it from the app menu; importing a subscription follows the same flow as the Windows chapter: paste the link on the config page → import → enable → confirm nodes have loaded.

System Proxy: Desktop Environment vs. Command Line

The client's "System Proxy" switch writes into the desktop environment's proxy settings under GNOME/KDE, and browsers and most graphical apps pick it up automatically. Command-line tools, however, don't read the desktop proxy settings — export environment variables in your shell instead:

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 this to persist, add it to ~/.bashrc or ~/.zshrc; to cancel temporarily, unset each variable individually. Some desktop environments (or bare window-manager setups) have no unified proxy settings entry, in which case environment variables are the only universal method — or just use TUN directly.

TUN Mode and Permissions

Creating a virtual network adapter on Linux requires CAP_NET_ADMIN privilege. Clash Verge Rev requests elevation before enabling TUN (a pkexec authorization dialog pops up); approve it and the client grants the core the needed capabilities. If that authorization flow fails, you can manually add the capability bits to the core's executable (adjust the path to match your actual install location):

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

After enabling TUN, it's best to turn off the system proxy switch to avoid a loopback caused by two layers of takeover stacking.

Headless: Running the Mihomo Core Directly

Servers and router setups skip the graphical client entirely and run the Mihomo core directly (per-architecture builds are on the download page's core tab). Place the binary in /usr/local/bin, put the config file at /etc/mihomo/config.yaml, and keep it running 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 it as /etc/systemd/system/mihomo.service, then enable it with sudo systemctl enable --now mihomo. The config content can be the YAML returned directly from your subscription address; once external-controller is set up, you can pair it with a web-based panel for remote management.

↑ Back to table of contents

CH-06 · Config Troubleshooting: A Minimal Config, Key Fields, and an Error Reference Table

A Minimal Working Config

Configs pushed by subscriptions can run hundreds of lines; when troubleshooting, start with the minimal structure to understand the skeleton. Here's a minimal config that runs as-is (the node section is left empty — this is just to illustrate the structure):

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

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

proxies: []

proxy-groups:
  - name: Proxy Selection
    type: select
    proxies:
      - DIRECT

rules:
  - GEOIP,CN,DIRECT
  - MATCH,Proxy Selection

Top to bottom: general fields (port, LAN, run mode, log level, control interface) → DNS section → node list → proxy groups → rules. Field-by-field details are in YAML Structure Walkthrough, and the selection logic for the four proxy-group types is in Proxy Group Selection Guide.

Key Fields at a Glance

mixed-port: the combined HTTP/SOCKS listening port that the system proxy points to; if you change it, update the system proxy setting to match. allow-lan: whether other devices on the LAN can treat this machine as a proxy gateway — enable with care depending on how trusted the network is. mode: rule (route by rules) / global (everything through the proxy) / direct (everything direct) — keep it on rule day to day. log-level: switch to debug for detailed logs while troubleshooting, info otherwise. external-controller: the RESTful control interface address that graphical clients and web panels use to read and write core state.

DNS and fake-ip Troubleshooting

In fake-ip mode, the core returns a fake address from a reserved block for every domain, mapping it to the real target once the connection is established — fast resolution, no leaks, but a downside for a few scenarios that rely on real IPs (LAN service discovery, some game matchmaking), which will misbehave. Add the affected domains to fake-ip-filter, or switch back to redir-host mode entirely. Another common misdiagnosis: an HTTPS certificate error in the browser after enabling the proxy is usually unrelated to DNS or the proxy itself, and instead traces back to system clock drift or a captive portal — see HTTPS Certificate Error Breakdown for the diagnostic flow.

Common Error Reference Table

A Fixed Troubleshooting Order

Regardless of platform, config-related failures converge on the same order: first confirm the subscription is fetching properly (no errors on the config page, node list non-empty) → then confirm the core is running (no startup errors in the log, port listening) → then confirm the takeover method is active (system proxy applied, or the TUN adapter created) → only then look at rules and nodes themselves. Skipping steps is the main reason troubleshooting wastes time. Quick answers to single questions are organized by category on the troubleshooting Q&A page; if the relationship between configs, subscriptions, and nodes is unclear, read Profile Basics first, then come back to follow along.

↑ Back to table of contents