Complete Clash Setup Guide for All Platforms

01General Preparation

The steps differ across the five platforms, but what you need before starting is identical. This chapter covers every shared prerequisite once; each platform chapter below assumes you've already read it.

Get a subscription link ready

A Clash client itself is just an "executor": it reads a config file and routes traffic through the nodes and rules defined there. Node information comes from a subscription link — a URL starting with https://, issued by your service provider, which the client periodically fetches to refresh the node list. Before installing, confirm three things: first, the link opens directly in a browser and returns plain text (usually YAML or Base64-encoded content), not a 404 or a login page; second, the link is a Clash-format subscription — if your provider only gave you single share links like ss:// or vmess://, they need to go through subscription conversion before a Clash client can read them; third, the link hasn't expired. For diagnosing an abnormal subscription response, see fixing subscription parse failures.

Choosing a client: top pick per platform

The Clash ecosystem has several GUI clients that share the same core but differ in interface and extras. Across all platforms, this site recommends Clash Plus: it runs on all five platforms, with subscription management and the TUN toggle built into the GUI, and it installs directly from the App Store on iOS. Desktop alternatives are Clash Verge Rev (the top pick on Linux) and FlClash. Full comparison below:

Clash for Windows and ClashX Meta, both discontinued, remain available as archived downloads for existing users migrating away; new installs shouldn't pick them.

Four terms you need to know first

• Mixed port (mixed-port): the local proxy port the client listens on, default 7890, accepting both HTTP and SOCKS5. System proxy settings and manually configured apps both point here.
• System proxy: an OS-level proxy setting. Once enabled, apps that respect it (browsers, most desktop software) send traffic to 127.0.0.1:7890; apps that ignore the system proxy (some CLI tools, games) are unaffected.
• TUN mode: the client creates a virtual network adapter and captures all outbound traffic at the network layer, covering apps that ignore the system proxy. Requires admin/elevated permission. See TUN mode vs. system proxy for how the two mechanisms differ.
• Proxy groups and rules: the part of the config file that decides which traffic goes through which node. Your subscription usually ships with a working set already, so beginners don't need to touch it.

More terminology is collected in the Glossary — jump there any time you hit an unfamiliar term in the text.

02Windows Setup

Download and install

Get the Clash Plus installer (.exe) from the Windows section of the download page. Most current x64 machines can just grab the default package; on ARM devices (e.g., Snapdragon laptops), check the architecture noted in the filename first. When you run the installer, Windows SmartScreen may show "Windows protected your PC" — a generic warning for any newly published installer — click "More info → Run anyway" to continue. Walk through the wizard with the default path; once done, the client appears in the Start menu, and after its first launch it lives in the system tray at the bottom-right of the taskbar rather than on the taskbar itself. If you can't find the window, click the small tray arrow to expand hidden icons.

Import a subscription

Open the main window, go to the "Profiles" page, paste the subscription link into the URL box, and click import. The client downloads the subscription content and generates a config file; a new profile card appears in the list — click it to activate. Switch to the "Proxies" page: if you see proxy groups and a node list, the subscription parsed correctly. If the list is empty or shows an error, go through the checklist in fixing subscription parse failures. For what each panel does, see a walkthrough of the client interface.

System proxy and TUN

Back on the main screen, flip the "System Proxy" toggle — the client writes 127.0.0.1:7890 into Windows' Internet Options, and browser traffic takes effect immediately. To capture global traffic beyond CLI tools and UWP apps, switch to TUN mode instead: the first time you enable it, it requests admin permission to install a virtual adapter service (some clients call this "Service Mode" — install the system service in Settings before turning on TUN). Once enabled, you'll see a new network adapter under "Settings → Network & Internet → Advanced network settings" — that's the TUN virtual adapter. Pick either system proxy or TUN; running both at once doesn't make things faster.

Windows-specific pitfalls

• Port already in use: startup fails with bind: address already in use, meaning port 7890 is held by another process (often a leftover from another proxy client). To locate it:

netstat -ano | findstr :7890
tasklist /FI "PID eq <PID from previous step>"

Kill the process holding the port, or change the mixed port in the client's settings to a free one like 7891. Full steps in resolving the port 7890 already-in-use conflict.

• UWP apps ignore the proxy: Store apps are sandboxed away from loopback addresses by default, so they can't reach 127.0.0.1 even with the system proxy on. Use TUN mode to bypass this, or grant a specific app loopback access with the built-in CheckNetIsolation tool.
• Security software blocking the virtual adapter: some security suites prevent TUN driver installation or delete the service files. If service installation fails, add the client's install directory to your security software's trusted list and try again.
• Auto-start not working: after enabling auto-start in the client's settings, also confirm the entry is "Enabled" under Windows "Task Manager → Startup apps" — some optimization tools disable it.

03macOS Setup

Download: check your chip architecture first

macOS installers come in Apple Silicon (M-series) and Intel builds — the wrong one either won't open or runs slower through the translation layer. To check: click the Apple menu → "About This Mac"; if the chip line says "Apple M…" grab the arm64 build, if it says "Intel" grab the x64 build. Running uname -m in Terminal and reading arm64 or x86_64 works too. Get the matching Clash Plus .dmg from the macOS section of the download page.

Installing and clearing the first-launch block

Double-click to mount the dmg and drag the app icon into Applications. On first launch, Gatekeeper may say "can't be opened because it is from an unidentified developer" or "is damaged": for the former, go to "System Settings → Privacy & Security" and click "Open Anyway" near the bottom of the page; the latter is caused by the quarantine attribute and is fixed with one Terminal command:

xattr -dr com.apple.quarantine "/Applications/<client name>.app"

Once it launches, the client's icon appears in the top menu bar rather than the Dock — that's the standard form for Clash clients on macOS, and the main window opens from that menu bar icon.

Importing a subscription and the system proxy

The import process is the same as Windows: paste the URL on the Profiles page, download, select. Turning on "System Proxy" writes the proxy into the settings of your current network service (Wi-Fi or Ethernet), and macOS prompts for your login password or Touch ID the first time — that's the normal authorization for changing network settings, and you must allow it or the toggle will snap back off. To verify: under "System Settings → Network → Wi-Fi → Details → Proxies", Web Proxy (HTTP) and Secure Web Proxy (HTTPS) should both point to 127.0.0.1:7890.

TUN mode

Enabling TUN on macOS also requires authorization: the client requests installing a privileged helper or system extension — allow it under "Privacy & Security" when prompted. Once enabled, ifconfig shows a new interface starting with utun. Terminal tools and apps that ignore the system proxy get captured from then on.

macOS-specific pitfalls

• Proxy only written to one network service: the system proxy is stored per network service (Wi-Fi, Ethernet, USB adapter). If the proxy seems to "stop working" after switching interfaces, it's usually because the new interface never got the setting — just toggle the system proxy off and back on.
• Port already in use: on macOS, run lsof -nP -iTCP:7890 -sTCP:LISTEN to see the process name and PID holding the port.
• Leftover proxy after quitting: if the client crashes, it may not restore the system proxy in time, which looks like lost internet access. Manually uncheck it on the Network proxy settings page, or relaunch the client and quit it normally once.
• Migrating from ClashX Meta: ClashX Meta is discontinued and kept as an archive on the download page. Moving to Clash Plus just means re-importing your subscription link — no need to carry over config files.

04Android Setup

Download: pick the right ABI

Android installers (.apk) are split by CPU architecture, mainly arm64-v8a for most phones from the past several years, and armeabi-v7a for older 32-bit devices. If unsure, try the arm64 build first and switch to v7a if you get an "app not installed" error or a crash. Grab Clash Plus from the Android section of the download page; prefer Surfboard for a leaner interface, or FlClash for an experience closer to the desktop clients.

Installing and permissions

After downloading the apk in your browser, tapping install triggers "For your security, installing unknown apps is blocked." Follow the prompt into Settings, grant your browser (or file manager) permission to "install unknown apps," then go back and continue installing. Some OEM ROMs (MIUI, ColorOS, etc.) add an extra risk confirmation dialog — just choose to continue.

Import a subscription

Open the client, go to the Profiles page, create a new profile, choose "Import from URL," paste the subscription link, and save. Once fetched, the profile appears in the list — check it to enable. Some clients auto-detect subscription links from the clipboard, so copying a link and opening the app can pop up an import confirmation directly.

VPN tunnel: Android's version of TUN

Android has no desktop-style system proxy toggle; instead, clients use the system's VpnService API to create a local VPN tunnel that captures traffic — equivalent to TUN on desktop, and no root required. The first time you tap connect, the system shows a "Connection request" dialog that you must allow; a key-shaped VPN icon then appears in the status bar, confirming it's active. This "VPN" is just a local traffic tunnel — the Clash core still processes everything by its rules.

Android-specific pitfalls

• Killed in the background: battery-saving policies on many OEM ROMs are the number-one culprit — if the proxy drops and the notification icon disappears after the screen has been locked a while, the system has killed the client's process. Fix: set the client's battery policy to "unrestricted/no optimization" in system settings, and lock it in the recent-apps card; MIUI also needs it whitelisted under "Autostart management."
• Per-app proxy: the Access Control/per-app proxy setting in the client lets you specify which apps use the VPN. If a banking app refuses to run because it detects a VPN, just exclude it from the list.
• Conflicts with other VPNs: Android only allows one active VpnService at a time, so connecting Clash automatically disconnects other VPN apps — that's expected behavior.
• Subscription update fails on mobile data: some subscription domains resolve incorrectly over mobile data — switch to Wi-Fi, or connect the proxy first before updating.

05iOS Setup

Installing from the App Store

Clash Plus is the top pick on iOS — search and install it directly from the App Store, or follow the store link from the iOS section of the download page. Its official site is clashplus.io; check the App Store listing for feature details and changelogs. Since iOS apps are distributed only through the system store, installation has no extra authorization steps — it's just like installing any other app.

Import a subscription

Open the app, go to the Profiles page, choose "Add via URL," paste the subscription link and confirm. If your provider's page has an "Import to Clash" button, tapping it in Safari on iOS launches the app directly and completes the import — quicker than pasting manually. After importing, check the proxy list to confirm the groups loaded.

Enabling the VPN configuration for the first time

Like Android, iOS uses the system's Network Extension to create a VPN tunnel that captures traffic. The first time you tap connect, the system shows a ""Clash Plus" Wants to Add VPN Configurations" dialog — tap Allow and verify with Face ID/Touch ID or your passcode. After that, an entry appears under "Settings → General → VPN & Device Management → VPN," its connection state syncs with the in-app toggle, and a VPN badge in the status bar confirms it's active.

iOS-specific pitfalls

• Some apps don't pick up a node switch: certain apps reuse existing connections, so switching nodes or rules can look like "still using the old route." Fully close and reopen the app, or disconnect and reconnect the VPN once.
• VPN toggle snaps back off: usually means the subscription has no usable nodes or failed to parse. Check the error in the app's log page first, then follow the subscription-related entries in the FAQ.
• Disconnects in Low Power Mode: the system may reclaim the background network extension in Low Power Mode — reopening the app and tapping connect once restores it.
• Multi-device sync: each iPhone/iPad under the same Apple account has an independent install and config — subscription links need to be imported separately on each, and VPN configurations don't sync through iCloud.

06Linux Setup

Installing a GUI client

Clash Verge Rev is the top pick on Linux desktops, shipping .deb and .rpm packages; FlClash is the alternative. Grab the right package for your distro from the Linux section of the download page and install it locally:

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

# Fedora / openSUSE family
sudo rpm -i clash-verge-rev.x86_64.rpm

Using apt install ./package-name instead of dpkg -i resolves dependencies automatically. Launch it from the app menu after installing; subscription import works the same as other desktop platforms: paste the URL on the Profiles page, download, select, activate.

System proxy: differences between desktop environments

On GNOME/KDE, the client's "System Proxy" toggle writes into the desktop environment's proxy settings, taking effect immediately for apps that respect it, like Firefox and Chromium. On GNOME, verify it with gsettings:

gsettings get org.gnome.system.proxy mode
# output 'manual' means it's active

Many Linux programs — command-line tools especially — ignore the desktop proxy and only respect environment variables. To set the proxy for the current shell session:

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

Add these to ~/.bashrc to make them persistent, but note this affects every terminal session — remember to unset them when not needed.

TUN mode and permissions

Creating a TUN virtual adapter requires the CAP_NET_ADMIN capability. Clash Verge Rev requests elevated permission through a built-in service — install the service in Settings, then turn on TUN. If you're running the core binary manually, grant the capability directly:

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

Once enabled, ip addr shows a new utun/Meta interface, and the routing table is maintained automatically by the core's auto-route.

Headless setups: Mihomo core + systemd

Servers and routers don't need a GUI — run the Mihomo core directly. Grab the archive for your architecture from the core section of the download page, extract it, and place the binary at /usr/local/bin/mihomo. Save your subscription's YAML output as the config file at /etc/mihomo/config.yaml, then write a systemd unit:

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

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

[Install]
WantedBy=multi-user.target

Save it as /etc/systemd/system/mihomo.service, then run sudo systemctl daemon-reload followed by sudo systemctl enable --now mihomo. Verify the proxy works:

curl -x http://127.0.0.1:7890 -I https://www.gstatic.com/generate_204
# HTTP/2 204 means the connection is healthy

Linux-specific pitfalls

• AppImage/Flatpak sandboxing: sandboxed builds may not be able to install the privileged service, making TUN unavailable — prefer native deb/rpm packages.
• Missing tray icon on Wayland: some Wayland desktops don't show a tray by default — install the relevant tray extension for your desktop environment (e.g., GNOME's AppIndicator extension).
• The systemd service doesn't refresh the subscription: the core itself doesn't manage subscriptions — set up a scheduled job to fetch updates yourself (curl -o /etc/mihomo/config.yaml "your-subscription-link" in cron), then run systemctl restart mihomo to apply.

07Configuration FAQ

Core fields at a glance

Regardless of platform, these fields near the top of the config file control the client's basic behavior — check them first before troubleshooting anything else:

A minimal config skeleton that actually runs looks like this (nodes and rules come from your subscription and are omitted here):

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
  nameserver:
    - https://223.5.5.5/dns-query

Subscription update fails

If the update button spins and then errors out, check in order: ① open the subscription link directly in a browser and see whether it returns config text or an error page — an error page means the link has expired or been restricted by your provider; ② check whether "update via proxy" is checked in the client, and switch to updating directly (or the other way around) if the current proxy isn't working; ③ if the link is a generic share link rather than Clash format, it needs to go through a subscription conversion service first. Full details in the subscription troubleshooting checklist.

Proxy is on but pages won't load

If the toggle is green but the browser just spins, the break could be at any link in the chain: dead nodes, a proxy group pointed at an unavailable node, poisoned DNS resolution, or a system proxy that never actually got written. Start by running a latency test on every node from the Proxies page — if all of them time out, the subscription's nodes are the problem; if only some work, switch to a working one. If nodes are fine but one specific site won't load, a rule is probably routing it direct — switch to global mode temporarily to confirm. Full nine-step process in the connected-but-no-internet checklist.

Rules not applying or misrouting traffic

Clash matches rules top to bottom and stops at the first hit. Custom rules must sit above the subscription's rules to have a chance of matching; anything written after the MATCH catch-all rule never runs. The most direct way to check which rule a domain hit is to open the log page (level info or above), visit the target site, and read the match entry for that connection. Domain rules (DOMAIN-SUFFIX) only apply to connections where the domain name is available — traffic going out by raw IP needs an IP-CIDR rule instead.

Common fake-ip and DNS confusion

In enhanced-mode: fake-ip, the core returns a fake IP in the 198.18.0.0/16 range for every domain, with actual resolution happening at the exit node — so seeing a 198.18.x.x address when you ping a domain is expected, not a bug. If a specific program that needs a real IP (LAN discovery, some game launchers) breaks, add that domain to the fake-ip-filter list, or switch the whole setup back to redir-host mode. After changing any DNS-related config, restart the client so the system's DNS cache clears.

Port conflicts and running multiple clients

Running two proxy clients at once means whichever starts second will hit a port-in-use error. Either fully quit the old client (watch for leftover tray processes) or change mixed-port on one of them. After changing the port, update every place that manually points to 7890 — environment variables, in-app proxy settings — or you'll end up with "changed the port and now nothing connects." Commands for locating the process holding the port on all three platforms are collected in resolving the port 7890 already-in-use conflict.

Still stuck?

Frequent short Q&As are collected on the FAQ page, organized into basics, setup, usage tips, and troubleshooting; look up config fields and protocol terms in the Glossary; and if the issue seems to be the client itself, check Get the Client first to make sure you're running a currently maintained build.