Complete Clash Setup Manual for All Platforms

This page serves a different purpose from the Setup Guide: the setup guide is the shortest path, following it for a few minutes gets you a first connection; this page is a reference manual, laying out the full process, background, and known issues for every platform so you can check back at any point during installation. If this is your first time with Clash, we recommend going through the setup guide first and returning to the relevant chapter here if you hit a snag. Installer downloads for every client are centralized on the client download page — this page focuses on process, not direct download links.

CH 01Prep Work: What You Need Before Installing

Three things to have ready

First, a subscription link. The Clash client itself is just a traffic-routing tool — node information is delivered by your subscription provider. A subscription link is an HTTPS address given to you in the provider's user panel. Before installing, confirm you have this link and that it's copied in full — a truncated link is the number-one cause of import failures. See the subscription parsing failure checklist for details.

Second, a client that matches your device. The same subscription can be used across multiple devices and platforms, but each platform needs its own client — the table in the next section gives recommendations. Third, a few uninterrupted minutes. Installation itself is quick; most of the time goes into first-time authorization and confirming connectivity.

Choosing a client

Available clients and the recommended order per platform are as follows, matching the download page. Clash Plus covers desktop and mobile and is the top pick across all platforms; the other clients each have platform-specific strengths.

Rule of thumb: install one client per device. Running multiple clients at once causes conflicts over ports and system proxy settings — this is the first thing to rule out when troubleshooting. New installs of discontinued clients aren't recommended; migration paths for existing users are noted on the corresponding cards on the download page.

Basic terminology cheat sheet

A few terms come up repeatedly below, so let's align on them first. Core: the underlying program that actually handles traffic — current mainstream clients bundle the Mihomo core, with the graphical interface just a shell around it. Node: a single usable proxy route. Policy group: a set of nodes bundled together with a selection logic, such as automatic latency testing or failover. Rule: the matching condition that decides which policy group a given request goes through. For how these four relate and more concepts, see the glossary; the three policy group types are covered in detail in Policy Group Types Explained.

CH 02Proxy Modes: System Proxy vs. TUN

You'll run into two toggles — "system proxy" and "TUN mode" — in every platform's setup flow. This chapter covers how they work; the platform chapters that follow only cover where to find them.

How system proxy works

With system proxy enabled, the client writes its own local listening port (7890 by default) into the operating system's proxy settings. Apps that honor the system proxy — browsers, mainly — send requests to this port first, and Clash routes them according to your rules. The upside is no special permissions and instant effect when toggled; the limitation is it only works for apps that "choose to" honor the system proxy — plenty of command-line tools, games, and background services connect directly and bypass it.

How TUN mode works

TUN mode creates a virtual network adapter on your system and points the default route to it, so all traffic — whether or not an app honors the system proxy — passes through this adapter into Clash. The cost is higher permission requirements: on Windows you install a system service and authorize as administrator; on macOS you approve a system extension; on Android and iOS it shows up as a VPN authorization prompt. Use either TUN or system proxy, not both — enabling both doesn't stack any effect.

Rule, global, and direct modes

Orthogonal to the two toggles above is the outbound mode: rule mode matches each request against your rule sections one by one, sending it wherever it matches — this is the everyday recommendation; global mode routes all traffic through a single policy group, useful only as a temporary check for "is a rule failing to match"; direct mode sends all traffic without a proxy. A common troubleshooting trick is to switch to global temporarily — if global works but rule mode doesn't, the problem is narrowed down to your rule section. See what each section of a config file means in YAML Structure Explained Section by Section.

CH 03Windows: Install, Subscriptions, and Service Mode

Download and install

Get the installer from the download page's Windows section — Clash Plus is the first choice, with Clash Verge Rev, FlClash, and Clash Nyanpasu as alternatives. The installer is a standard setup wizard; default options work fine. Keep the default install path if possible, and avoid deep folders with Chinese characters or spaces in the path, as some components are path-sensitive.

On first run, Windows may pop up a blue SmartScreen prompt — this is the system's generic block for executables from newer download sources. Click "More info" → "Run anyway" to continue. Some security software may flag the virtual adapter driver used by proxy tools as suspicious; add the install directory to the trusted list rather than disabling your security software entirely.

Import a subscription

Open the client, go to the "Subscriptions" or "Profiles" page, paste your subscription link into the URL field, and click import. The client downloads and parses the subscription; once successful, the proxy page shows your node and policy group lists. If import fails or the list is empty, copy the link fully and retry first, then work through the subscription checklist item by item — don't jump straight to reinstalling.

System proxy and TUN

For everyday use, toggle "System Proxy" on the main screen — browser traffic then routes through Clash. To capture command-line or game traffic, switch to TUN instead: mainstream clients package the system service TUN needs as a one-click install; the first time you enable it, you'll get an administrator prompt (UAC), and after approval the service stays running so toggling TUN afterward won't prompt again. Turn off system proxy before enabling TUN.

Platform-specific issues

Port already in use: if startup reports port 7890 or 9090 in use, find out what's holding the port before deciding whether to kill the process or change the port. Open an administrator terminal and run:

netstat -ano | findstr :7890
tasklist | findstr <PID from the previous step>

The last column of the first command is the PID of the process holding the port; the second command looks up its name. The usual culprit is another proxy client that didn't fully exit. The full process for changing ports is covered in Fixing "Port Already in Use" Errors.

Leftover proxy settings: if the client crashes or is force-closed, it may not have time to restore the system proxy, leaving you unable to load any web pages after it exits. Restore manually: "Settings → Network & Internet → Proxy," and turn off "Use a proxy server." Launch at startup: enable auto-start and "silent start" in the client's settings to avoid the main window popping up on every boot.

CH 04macOS: Chip Architecture, Gatekeeper, and System Extensions

Confirm your chip architecture before downloading

macOS installers come in two variants — Apple Silicon (M-series chips) and Intel — and picking the wrong one causes noticeable slowdowns or even failure to launch. If you're not sure which chip you have, run this in Terminal:

uname -m

An output of arm64 means choose the Apple Silicon build; x86_64 means choose the Intel build. Then grab the matching dmg from the download page's macOS section — Clash Plus is the first choice, with Clash Verge Rev and FlClash as alternatives.

Install and first launch

Open the dmg and drag the app icon into your Applications folder, then launch it from Launchpad or the Applications directory. On first open, Gatekeeper may say it can't verify the developer: go to "System Settings → Privacy & Security," scroll to the bottom, find "Open Anyway" next to the blocked app, and confirm. If you see "the app is damaged and can't be opened," the downloaded file has been tagged with a quarantine attribute — run the following in Terminal (swap in the actual app name) and reopen it:

xattr -cr /Applications/YourClientName.app

Import a subscription and set system proxy

Subscription import works the same as on Windows: paste the link on the subscription page, import, and confirm the node list appears. When you enable "System Proxy," macOS will prompt for authorization to change network settings — enter your login password once to confirm. After enabling it, you can verify it's actually active by checking "System Settings → Network → [current network] → Details → Proxies" and confirming HTTP/HTTPS proxy points to the matching port on 127.0.0.1.

TUN and system extensions

Enabling TUN on macOS requires approving a system or network extension: the first time you turn it on, follow the prompt to allow the extension under "System Settings → Privacy & Security" — some machines require restarting the client once afterward. If you use multiple "network locations" or are connected to both Ethernet and Wi-Fi at once, proxy settings are saved per network service, so if the proxy seems to stop working after switching networks, check first whether the currently active network service is the one you originally configured.

Platform-specific issues

Extension authorization can occasionally get reset after a system update — if TUN suddenly stops working, check "Privacy & Security" first to confirm the extension is still allowed. To uninstall the client, use its built-in uninstall option, or turn off system proxy and TUN inside the app before deleting it; dragging it straight to the Trash can leave proxy settings behind, which you can fix the same way as above — turn off the proxy manually in network details.

CH 05Linux: Desktop Clients and Server Deployment

Desktop distributions: installing Clash Verge Rev or FlClash

On Debian/Ubuntu-based systems, get the deb package from the download page's Linux section and install it:

sudo dpkg -i downloaded-package.deb
sudo apt-get -f install

The second command fills in any missing dependencies automatically. On RPM-based distributions, use the matching rpm package with your distro's package manager. After installing, launch it from your application menu — subscription import works the same as on other desktop platforms.

System proxy on the desktop

Linux has no single unified "system proxy" entry point — the client's system proxy toggle affects GNOME and KDE desktop proxy settings, but only applications that honor that setting. Terminal sessions need their own environment variables:

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

These variables only apply to the current terminal session and are lost when you close it; for a persistent setup, add them to your shell config file — though it's often simpler to just use TUN mode to capture the whole machine. Enabling TUN on Linux also requires elevated permissions; the client will guide you through installing a service or requesting root authorization.

Headless servers: deploying the Mihomo core directly

Server and router setups don't need a graphical client — you can run the Mihomo core directly. The core package is available in the download page's core section. Basic steps: extract the binary to /usr/local/bin/mihomo, put your config file at /etc/mihomo/config.yaml, and write a systemd service:

[Unit]
Description=mihomo daemon
After=network-online.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 run:

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

A status of active (running) means it started successfully. The config file format is exactly the same as what desktop clients use — see Config File Explained Section by Section for what each section means.

Platform-specific issues

Port 53 conflicts: if your config enables the DNS module listening on port 53, it'll conflict with systemd-resolved, and the startup log will report "address already in use." Either fix works: change the DNS listener in your config to a non-53 port like 0.0.0.0:1053, or disable systemd-resolved's stub listener. Checking port usage:

ss -lntp | grep 7890

Permission issues: TUN mode requires the NET_ADMIN capability — running via systemd as root satisfies this naturally; if running manually in the foreground, remember to add sudo.

CH 06Android: APK Install and VPN Authorization

Installing the APK

Get the APK from the download page's Android section — Clash Plus is the first choice, with Clash Meta for Android, FlClash, and Surfboard as alternatives. The first time you install an APK downloaded via the browser, the system asks you to grant "install unknown apps" permission — follow the prompt to enable it for your browser or file manager, then return and continue installing. This is Android's standard flow for installers from outside the app store.

Import a subscription and connect for the first time

Open the app, paste your subscription link on the subscriptions/profiles page, and import it. On phones, it's often easier to copy the link first, then open the app directly — most clients detect the clipboard and offer a one-tap import. The first time you tap the connect button, the system shows a "[App] wants to set up a VPN connection" authorization dialog — on Android, Clash captures traffic through the system's VPN interface, equivalent to TUN mode on desktop. Tap "OK," and a key icon in the status bar confirms it's active. If you don't see this prompt, or you tapped decline by mistake, go to "Settings → Network → VPN," delete the entry, and reconnect to trigger it again.

Platform-specific issues

Killed in the background: heavily customized Android skins are often aggressive about killing background apps, showing up as the proxy disconnecting after the screen has been locked for a while. Fix: add the client to your battery optimization whitelist and allow background activity and auto-start — the exact menu names vary by manufacturer, usually under "Battery" or "App management." Private DNS conflicts: if the system's "Private DNS" is set to a specific hostname, it can interfere with the client's own DNS handling — when troubleshooting resolution issues, switch Private DNS back to "Automatic" and test again. Per-app proxying: the client's settings let you specify which apps go through the proxy and which connect directly — if a banking app is sensitive to proxies, adding it to the direct-connect list is easier than turning off the proxy entirely.

CH 07iOS: Getting the App and VPN Configuration

Getting the client

Clash Plus for iOS is distributed via the App Store — see the store link and details on the download page's iOS section. Once installed from the App Store, updates are handled automatically by the store, so there's no manual installer to maintain — this is the biggest process difference between iOS and the other platforms.

First-time setup and authorization

Open the app, paste your link on the subscriptions page and import it — the flow matches Android. The first time you connect, the system asks to "Add VPN Configuration" and requires Face ID/passcode verification — every proxy client on iOS works through the system's VPN framework, so this authorization step is unavoidable. Once done, a matching entry appears under "Settings → VPN," and a VPN indicator in the status bar confirms it's active. From then on you can connect and disconnect either inside the app or directly via the VPN toggle in system settings.

Platform-specific issues

Disconnects after switching networks: the VPN tunnel rebuilds when switching between Wi-Fi and cellular, occasionally requiring a manual reconnect from within the app; if the client offers an "on-demand connection" option, turning it on is recommended so the system re-establishes the tunnel automatically when needed. Subscription updates: iOS background refresh is limited by system scheduling, so a subscription may expire if the app hasn't been opened in a while — if every node suddenly times out, open the app and manually refresh the subscription first before testing further. Rules and configuration: the subscription and config syntax used by the iOS client is identical to desktop, so policy group and rule adjustments work the same way — there's no need to maintain a separate config for iOS.

CH 08Configuration FAQ: Troubleshooting After Installation

YAML indentation and field name typos

When editing a config file by hand, the most common mistake is indentation: YAML uses two spaces per level and forbids tab characters; fields at the same level must align, and list items need a space after the -. When the client reports "config load failed" with a line number, first check whether that line's indentation matches its context, then check the field name for typos — a slip like proxy-groups written as proxy-group is easy to miss and the error message is often not very direct. A minimal working general section looks like this:

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

mixed-port is a combined port that accepts both HTTP and SOCKS; external-controller is the local management interface. These two ports are the same ones behind the "port already in use" issue covered per platform above — restart the client after changing either. See YAML Structure Explained Section by Section for the full breakdown.

General approach to port conflicts

The commands for checking port usage on each platform were given in their respective chapters (netstat on Windows, ss or lsof on macOS/Linux). General diagnostic order: first check whether another proxy client failed to fully exit — if so, quit the old client; if not, change the local port instead — update 7890 to another free port in the config file or client settings, and update anything that depends on it (browser extensions, terminal environment variables) at the same time. See the full port-conflict write-up for the complete process.

Subscription issues

Import errors, empty node lists, and update failures all follow the same diagnostic chain: link integrity → response format → whether the subscription has expired → client compatibility. See the subscription checklist for the step-by-step method. One general tip worth adding: open the subscription link directly in a browser — if it returns a block of text rather than an error page, the link itself works and the issue is on the client side; if it returns an error page or a blank response, contact your subscription provider directly.

Proxy is active but the browser shows a certificate error

If the browser shows something like "your connection is not private" after enabling the proxy, it's usually unrelated to the client's config: first check your system clock (a few minutes of drift is enough to break certificate validation), then try a different node — if it still happens, look at other causes. See the certificate error troubleshooting guide for a breakdown by error type.

Can't pick a node, or switching nodes has no effect

In rule mode, switch nodes manually inside the corresponding policy group, not from the node list directly — requests hit the policy group, and the node currently selected within that group is the actual exit point. Url-test type groups pick automatically based on latency results, so manually specifying a node has no effect by design — if you want manual control, set the group you use to the select type instead. See the mechanics and config snippets for all three policy group types in Policy Groups Explained.

Still stuck?

More Q&A organized by symptom is available on the FAQ page; for conceptual questions, check the glossary. When reporting an issue, include three things: platform and client name, steps to reproduce, and the error line from the client's log — this cuts back-and-forth down to a minimum.