Clash Setup Guide for Every Platform

Before You Start: General Preparation

No matter which platform you're on, using Clash follows the same basic logic: install a client, feed it a config, and route your system traffic through it. This chapter covers the concepts and prep work that apply across every platform, so the platform chapters below won't repeat them.

Three Terms Worth Separating

A lot of setup confusion comes from lumping three different things together. The core refers to command-line programs like Mihomo, which actually process traffic and match rules — it has no interface. The client is the graphical app wrapped around the core, such as Clash Plus, Clash Verge Rev, or FlClash; every toggle you click ultimately gets translated into parameters the core understands. A subscription is a link provided by your service — the client periodically fetches it to pull down a config file containing nodes and rules. In short: the subscription provides content, the client handles the interface and scheduling, and the core does the actual work. For more terms, see the Glossary.

Three Things You Need Before Starting

• A subscription link. Provided by your service, usually a long URL starting with https. Treat it like a login credential — don't share it publicly.
• An installer for your platform. Recommended clients and where to get them are on the download page; Clash Plus is the top pick across every platform, and the table below gives a quick overview.
• Ten uninterrupted minutes. Initial setup involves system authorization prompts, and stepping away mid-way makes it easy to miss a dialog.

System Proxy vs. TUN Mode, Explained Once

Both terms come up in every platform chapter, so let's clear them up here first. System proxy registers a proxy address (usually 127.0.0.1 plus a port) in your OS network settings — any program that respects this setting, including browsers and most common apps, hands its traffic to Clash. TUN mode goes further: the client creates a virtual network adapter, and all system traffic passes through it first, regardless of whether an app even recognizes proxy settings.

Windows: Install, Subscribe, and Service Mode

Download and Install

Grab the installer from the Windows section of the download page — Clash Plus is the top pick, with Clash Verge Rev and FlClash as equally solid alternatives. The installer is a standard setup wizard; just click through it. Keep the default install path if you can — deep folders with non-English characters or spaces occasionally trigger core startup errors that are a pain to troubleshoot.

On first launch, Windows SmartScreen may show a blue "Windows protected your PC" warning. This is a routine block on downloaded files, not a virus alert — click "More info," then "Run anyway." If your antivirus software quarantines the installer, restore it, add it to the trusted list, and reinstall.

Import Your Subscription

Open the client, find the "Subscription" or "Profiles" page, paste the full subscription link into the input box, and click import. The client will fetch the config, and once successful, a profile entry appears in the list — click it to select and activate it. Then head to the "Proxies" tab; you should see node groups and a node list. Seeing nodes means the subscription step worked. If the fetch fails, first check that the link was copied in full (a trailing space or a missing character will break it), then confirm your current network can actually reach the subscription URL.

System Proxy and TUN

Toggle "System Proxy" on in the client's main screen, and it will automatically write 127.0.0.1 plus the mixed port into Windows' proxy settings — browsers pick it up immediately. TUN mode usually requires installing "Service Mode" first — a background service that runs alongside the system and gets the client the permissions it needs to create a virtual adapter. Find the service mode install button in Settings, accept the UAC prompt, and then flip on the TUN toggle. If you lose all connectivity after enabling it, security software is likely blocking the virtual adapter driver — add the client to the trusted list and try again.

Windows-Specific Issues

• Launch at startup: just check the auto-start option in client settings. If the tray icon is missing after boot, check whether it's disabled under Task Manager's "Startup apps."
• Leftover proxy settings: if the client crashes or is force-closed, the system proxy setting may stay on, making it look like closing the client broke your internet. Go to Settings → Network & Internet → Proxy and manually turn off "Use a proxy server" to fix it.
• Port conflicts: bind-related errors in the log usually mean a port clash — switch to a different mixed port (e.g., 7897 instead of 7890). See Reading Clash Logs for how to check the logs.

macOS: Chip Version, Authorization, and System Proxy

Pick the Right Chip Build First

macOS installers come in Intel and Apple Silicon (M-series) builds. Click the Apple menu in the top-left corner → "About This Mac"; if the chip line starts with "Apple M," download the Apple Silicon build — if it says "Intel," download the Intel build. Picking the wrong one won't damage your system, but it either won't launch or will run through a translation layer and lose performance. The macOS section of the download page lists both builds side by side.

Install and First Launch

You'll get a .dmg disk image — double-click to open it, then drag the app icon into the "Applications" folder alongside it; that drag is the entire macOS install process. On first launch, the system may warn that the app is from an unidentified developer, or that it's "damaged." For the former, go to System Settings → Privacy & Security and click "Open Anyway" at the bottom. The latter is caused by the quarantine attribute — open Terminal and run one command to clear it:

xattr -d com.apple.quarantine /Applications/AppName.app

Replace "AppName.app" with the actual name of the app you dragged in. Double-click again afterward and it should launch normally.

Subscription Import and System Proxy Authorization

Importing a subscription works the same as on Windows: paste the link on the subscription page, import, then activate. The difference is in system proxy — the first time you toggle "System Proxy" on macOS, the client may ask to install a "helper" and request your login password, since changing network preferences needs elevated permissions. This authorization only happens once; after approving it, the toggle works normally from then on. You can verify it under System Settings → Network → [current network] → Details → Proxies — you should see HTTP and HTTPS proxies pointing to 127.0.0.1.

macOS-Specific Issues

• TUN authorization: enabling TUN on macOS also depends on a helper or system extension approval — wherever the prompt points, go grant it there. If you denied it once, find the corresponding entry under Privacy & Security and re-enable it.
• Leftover proxy settings: same as Windows — if the client is force-quit, the proxy settings may remain. Uncheck them under the network's "Proxies" details page.
• ClashX Meta users: that project is no longer maintained. Its configuration concepts still apply, but consider migrating to a client that's still actively updated.

Linux: Packages, Desktop Proxy, and Terminal Proxy

Installing

Clash Verge Rev is the top pick for Linux desktops, with FlClash as an alternative; find the packages in the Linux section of the download page. Debian/Ubuntu-based systems use .deb packages — download it and install from the terminal:

cd ~/Downloads
sudo apt install ./clash-verge.deb

Using apt instead of dpkg means dependencies get resolved automatically. Once installed, launch it from the app menu, or just type the program name in the terminal. If the window opens blank, it's usually related to the desktop environment's WebKit component version — update your system packages fully and try again.

Desktop Environment System Proxy

The "System Proxy" toggle in the client usually writes settings automatically on mainstream desktops (GNOME, KDE). If your distro doesn't pick this up automatically, setting it manually is just a few commands. Using GNOME as an example:

gsettings set org.gnome.system.proxy mode 'manual'
gsettings set org.gnome.system.proxy.http host '127.0.0.1'
gsettings set org.gnome.system.proxy.http port 7890
gsettings set org.gnome.system.proxy.https host '127.0.0.1'
gsettings set org.gnome.system.proxy.https port 7890

Use whatever mixed port your client's settings page shows — this article uses 7890 throughout. To go back to direct connections, set mode back to 'none'.

Terminal and Command-Line Tools

Desktop proxy settings don't reach the terminal. To route git, curl, or package managers through the proxy, use 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

Setting these in the current shell only applies to that session; for a persistent setup, append them to ~/.bashrc or ~/.zshrc. The mixed port accepts both HTTP and SOCKS5 requests at once, which is why all three variables can point to the same port — that's exactly where the "mixed" name comes from. See Mixed Port and LAN Sharing for a fuller explanation.

Linux-Specific Issues

• TUN permissions: creating a virtual adapter needs elevated permissions, which the client typically handles via an authorization helper — approve the password prompt when it appears; if you deny it, the TUN toggle will immediately flip back off.
• Launch at startup: prefer the auto-start option in client settings. If you're used to systemd, you can build a custom user service, but keep in mind the desktop client depends on a graphical session — starting too early will make it fail to launch.
• Browser exceptions: Firefox uses its own proxy settings by default instead of the system's — go into Firefox's settings and select "Use system proxy settings."

Android: Package Architecture and VPN Authorization

Pick the Right Architecture

Android packages come in arm64, arm, and other CPU architecture variants; nearly every phone from the past few years is arm64, so download that build. If you're unsure, choose the universal package — it's a bit larger but never the wrong pick. Clash Plus is the top choice, with Clash Meta for Android and FlClash also available in the Android section of the download page. After downloading the .apk, the system will warn "Install unknown apps not allowed" — follow the prompt to grant your browser or file manager the "install unknown apps" permission to continue. This is Android's standard flow for installs outside the store.

Import Your Subscription

There are two ways to import a subscription on Android: copy the subscription link, open the client, and paste it under "Import from URL" on the profiles page; or, if your provider's page offers a "one-tap import" button, tap it and choose your installed client when the system asks which app to open it with — the link gets passed in automatically. After a successful import, remember to select and activate that profile — a lot of "imported but can't connect" reports turn out to be a profile just sitting in the list, unselected.

VPN Authorization and Battery Optimization

The Clash client on Android takes over traffic through the system's VpnService, no root required. The first time you tap the start button, the system shows a "Connection request" dialog — confirm it, and a key-shaped icon appears in the status bar, meaning the takeover is active. This step is the equivalent of TUN mode on desktop, which is why Android has no separate "System Proxy" toggle — starting the client takes over everything globally, and rules handle the splitting.

Just as important is keeping it alive: many customized Android skins have aggressive power-saving policies that kill background apps after the screen locks, showing up as "it disconnects after a while, then works again once I reopen the app." Address it point by point: set the client to "unrestricted" in battery settings; lock it in the recent-apps view; and if your manufacturer has an "auto-start manager," allow it there too.

Android-Specific Issues

• Per-app proxying: client settings usually include "Access Control," letting you specify which apps go through the proxy and which bypass it. Banking apps tend to be sensitive to proxies, so adding them to the bypass list reduces false risk flags.
• Conflicts with other VPNs: Android only allows one app to hold the VpnService at a time — if startup fails, check that no other VPN-type app is running.
• Private DNS: when the system's "Private DNS" is forced to encrypted resolution, it can conflict with the client's DNS takeover. Switch it back to automatic first when troubleshooting DNS issues.

iOS: App Store Install and VPN Configuration

Getting the Client

Clash Plus is the recommended pick on iOS, installed through the App Store — the link is in the iOS section of the download page; the app's official site is clashplus.io. Installing through the store means updates happen automatically, with no package management on your end — which is also why this chapter is shorter than the others: the store handles the step most prone to error.

Import Your Subscription

Open the app, paste your subscription link on the profiles or subscription page, and import — same as every other platform. iOS's clipboard permission prompt ("Allow [App] to paste from...") just needs to be allowed. After importing, confirm the profile is activated and that you can see groups and nodes in the list before moving on.

VPN Configuration Authorization and Daily Toggling

The first time you tap connect, iOS shows a system dialog: "'Clash Plus' Would Like to Add a VPN Configuration." Tap "Allow" and verify with your password or Face ID — this registers the app with the system's VPN framework, and it only needs to happen once. After that, a VPN icon in the status bar confirms the takeover is active. You can toggle it either inside the app or under Settings → VPN — the two stay in sync.

Usage Notes

• Rules still apply: the takeover method on iOS resembles TUN mode, but traffic is still split according to your config's rules — local traffic connects directly and isn't affected, so there's no need to toggle it constantly.
• Reconnect after switching profiles: after changing or updating your subscription, disconnect and reconnect once to make sure the new config loads fully.
• Battery awareness: keeping a VPN connection active does use a bit more battery, which is normal. If drain seems unusually high, check whether some rule is routing traffic through a longer path than necessary.

Config File: Understanding Every Section of the YAML

What your subscription pulls down is a YAML config file. You don't need to write it by hand day-to-day, but understanding it cuts your troubleshooting time in half. Here's a minimal skeleton example:

mixed-port: 7890        # mixed port, accepts both HTTP and SOCKS5
allow-lan: false        # whether LAN devices can connect
mode: rule              # run mode: rule / global / direct
log-level: info         # log verbosity

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

proxies: []             # node list, filled in by the subscription

proxy-groups:
  - name: Manual Select
    type: select
    proxies: []         # group members, filled in by the subscription

rules:
  - GEOIP,CN,DIRECT     # direct connect for mainland China IPs
  - MATCH,Manual Select # everything else goes to the group

The Key Fields, One by One

• mixed-port: the port local apps connect to Clash through. The 127.0.0.1:7890 you enter for system proxy refers to this. If it conflicts, change it to any free port and the system proxy setting updates accordingly.
• allow-lan: set to true, and other devices on the same network — smart TVs, game consoles — can point their proxy settings to this machine; pair it with a firewall rule. Full instructions are in Sharing a Proxy Over LAN.
• mode: rule splits traffic by rule, global sends everything through the proxy, direct connects everything directly. Stick with rule as the default day-to-day; see Proxy Modes Explained for the trade-offs among the three.
• dns: fake-ip mode speeds up resolution using virtual IPs and is the current mainstream default; if some app resolves incorrectly, try switching to redir-host to compare.
• proxy-groups: organizes nodes into groups. select is manual choice, url-test auto-picks based on latency testing, fallback switches to the next node when the primary fails. Switching nodes in the client UI is really just changing which item is selected in a select group.
• rules: matched top to bottom, stopping at the first hit. DOMAIN-SUFFIX matches by domain suffix, GEOIP by IP location, MATCH catches everything else. Rules in the wrong order often show up as "this site should connect directly but goes through the proxy instead."

Manual Edits vs. Subscription Updates

Be careful editing the config file your subscription generates directly: the next update will overwrite the whole thing, and your changes will disappear with it. For lasting customizations, use the client's "Override" mechanism, or add custom rules at your provider's subscription-conversion step instead — keep your changes living outside the subscription rather than fighting over the same file.

Verification, Maintenance, and Where to Troubleshoot

Three Checks to Confirm Everything Works

1. Check the nodes: the Proxies tab should list node groups; run a latency test on a group and most nodes should return a number. If everything times out, suspect the subscription or your local network before switching clients.
2. Check direct connections: visit a site in mainland China — it should load instantly and show DIRECT in the connection log against the matching rule name. If direct connections are slow too, the problem is your local network.
3. Check the proxy: visit a site that needs the proxy — the connection log should show a matching rule pointing to the node you selected. If both checks pass, the chain is working end to end.

Only Three Things for Routine Maintenance

First, update your subscription regularly — as your provider adjusts nodes, old ones in your config gradually stop working; most clients support setting an auto-update interval, so turn that on. Second, update the GeoIP database occasionally to keep location-based rules accurate. Third, keep the client updated — new versions often ship with core fixes bundled in. Before updating, make sure your subscription link is saved somewhere — it's the only thing you actually need to back up, since the config itself can always be re-fetched.

Where to Go When Something Breaks

• Can't connect, or things are slow: work through the layered slow-speed checklist to pin down whether it's the node, the route, or a local setting.
• Low latency in the dashboard but a poor experience: the two aren't the same thing — see how latency testing actually works.
• Error messages you don't understand: open the logs page and match entries against Reading Clash Logs to translate "it doesn't work" into a specific failure point.
• Random one-off questions: someone's probably already asked — check the FAQ, and look up unfamiliar terms in the Glossary.