Complete Clash Setup Guide

1.1Three things to confirm before you start

First, the subscription link. The Clash client itself is just a rule engine and traffic dispatcher; it doesn't come with any nodes. Node information is provided by a subscription link, usually from your provider's user panel or exported from a self-hosted server config. A subscription link is an HTTPS address that, when accessed, returns a Clash-format YAML config. Before installing, copy this link somewhere handy — every platform's import step will need it.

Second, platform and architecture. On desktop, confirm your OS version and CPU architecture: Windows needs x64 vs. ARM64; macOS needs Apple Silicon (M-series chips) vs. Intel, checkable under "About This Mac"; Linux needs to match the package format (deb or rpm) and architecture. On Android, most devices use arm64-v8a, while older devices may use armeabi-v7a. Picking the wrong architecture means the installer won't run, or performance will drop noticeably.

Third, permissions. System proxy is a user-level setting and can be written with normal privileges; TUN mode creates a virtual network adapter — Windows needs administrator rights to install a system service, macOS needs authorization, and Linux needs root or the corresponding capability bit. On managed devices under MDM or group policy, some settings may be locked; confirm the device allows network configuration changes before installing.

1.2Terminology conventions

The following terms appear repeatedly on this page; here's the fixed convention used throughout. For a fuller explanation of terms, see the glossary.

1.3Client selection cheat sheet

The table below lists available clients per platform and recommended order, matching the layout on the download page. Selection principle: prefer actively maintained clients with consistent UI and config logic across platforms; discontinued projects are listed only for reference and not recommended for new installs.

↑ Back to chapter list

2.1Config file structure

A Clash config file is a YAML document made up of five main sections: base port settings, DNS settings, the node list (proxies), policy groups (proxy-groups), and the rule list (rules). What a subscription returns is exactly such a complete file — understanding its structure lets you map every platform's UI back to it. A minimal, readable skeleton looks like this:

mixed-port: 7890        # Shared inbound port for both HTTP and SOCKS5
allow-lan: false        # Whether other devices on the LAN can connect
mode: rule              # Run mode: rule / global / direct
log-level: info

proxies:                # Node list, provided by the subscription
  - name: "NodeA"
    type: trojan
    server: example-server.net
    port: 443
    password: "********"

proxy-groups:           # Policy groups: organize nodes into switchable groups
  - name: "Proxy Select"
    type: select
    proxies: ["NodeA", "DIRECT"]

rules:                  # Matched top-down; first match wins
  - DOMAIN-SUFFIX,example.com,Proxy Select
  - GEOIP,CN,DIRECT
  - MATCH,Proxy Select   # Fallback rule, must be last

In day-to-day use you don't need to hand-write this file — the subscription already contains everything. But when you run into "this site goes out the wrong exit" or "this rule isn't taking effect," understanding the rules section is the prerequisite for troubleshooting: rules are matched top-down and stop at the first hit, so an out-of-order rule means everything after it never gets a chance. For a full walkthrough of rule syntax and priority, see the article "Clash Rule Priority Explained".

2.2Three run modes

Every client offers three run modes, with fixed behavior:

When troubleshooting, these three modes are a natural control group: if things work in direct mode but fail in rule mode, the problem is in a rule or a node; if all three modes fail, the problem is in your local network itself.

2.3Three ways to import a subscription, and updates

Nearly every platform supports the same import methods: URL import (paste the link, the client downloads it — the most common route), clipboard import (copy the link and the client auto-detects it), and local file import (manually download the YAML and add it from a file, useful offline). Step-by-step instructions and format differences for all three are covered in the article "How to Import a Clash Subscription Link".

Subscriptions imported by URL support automatic updates, typically every few hours to once a day by default, adjustable in the subscription entry's settings. Providers usually push traffic and expiration info via subscription response headers, which the client displays on the subscription card; local file imports have no update mechanism, so you'll need to re-download and replace the file when nodes change. For subscription update failures, see Chapter 08.

2.4Port conventions

Mainstream configs use mixed-port: 7890 for a combined inbound that accepts both HTTP and SOCKS5 on the same port; older configs may split these into port: 7890 (HTTP) and socks-port: 7891 (SOCKS5). The system proxy address written is always 127.0.0.1 plus the port above. When manually setting a proxy for a command-line tool or another device, use the actual port shown on the client's home screen — don't rely on memory, since default ports differ across clients.

↑ Back to chapter list

3.1Download and version selection

Go to the download page's Windows section to get the installer. Clash Plus is the top pick; alternatives include Clash Verge Rev (built with Rust + Tauri, low memory footprint), FlClash (Flutter-based, clean UI), and Clash Nyanpasu. Clash for Windows is discontinued and provided only for archival purposes — don't pick it for a new install, since its bundled legacy core has incomplete support for newer protocols and rule types. System requirement: Windows 10 64-bit or later; ARM laptops should use the ARM64 build, since the x64 build relies on an emulation layer on ARM devices with a noticeable performance cost.

3.2Installation steps

1. Double-click the installer. If a blue SmartScreen warning appears, click "More info" → "Run anyway." This is Windows's default prompt for installers without widespread distribution signatures, and it doesn't indicate anything wrong with the file itself.
2. Keep the default install directory if possible. If you customize the path, avoid directories with non-ASCII characters or spaces — some components have unstable compatibility with non-ASCII paths.
3. On first launch, Windows Firewall may prompt for network access — check "Private networks" and allow it; denying this will keep the core from being able to listen on the local port.
4. Open the client settings and confirm "Launch at startup" and "Start minimized" are set as you want, so you don't forget to turn the proxy back on after a reboot.

3.3Importing a subscription

Open the client's "Subscriptions" or "Profiles" page, click New, paste the subscription link, and confirm — the client downloads the config and creates an entry. Success shows up as a node count or traffic info appearing on the entry; if it stays stuck loading, first check whether your machine can reach the subscription URL directly — some subscription domains themselves require a proxy to access, in which case use clipboard import or import a local file first to get connected, then switch back to the URL subscription. After a successful import, go to the "Proxies" page and pick a node with normal latency.

3.4System proxy and verification

On the client's home screen, flip the "System Proxy" toggle — the client writes 127.0.0.1:7890 (use the actual port) into Windows's Internet proxy settings. Verify two ways: check the settings — open "Settings → Network & Internet → Proxy" and confirm "Use a proxy server" is on with a matching address and port; and check traffic — visit a site in a browser that should be routed through the proxy, and watch for a matching entry in the client's connections panel. Verify the listening port from the command line:

netstat -ano | findstr 7890

Output means the core is listening; no output means the core isn't running or the port has been changed — check the client logs first.

3.5TUN mode

System proxy only affects programs that read the OS proxy setting; UWP apps, some game clients, and command-line tools ignore it by default, and their traffic needs TUN mode to be intercepted. The fixed process for enabling TUN on Windows: first install the system service in the client settings (confirming a UAC prompt requires admin rights), then flip the "TUN Mode" switch once the service is installed. Signs it's working: Device Manager or "Network Connections" shows a new virtual adapter named Mihomo or similar, and apps that don't read the system proxy start showing connection activity. For a deeper explanation of the mechanics (the difference between a virtual adapter and system proxy, why DNS hijacking is necessary), see the article "How TUN Mode Works and How to Enable It".

3.6Windows-specific issues

• Port already in use: If the client reports a port conflict, use netstat -ano | findstr 7890 to find the PID holding it, end that process in Task Manager, or switch to a different port in the client settings. The usual culprit is another proxy app instance that didn't fully quit.
• No internet after quitting: An abnormal exit can leave the system proxy setting in place, causing every browser to fail to load. Go to "Settings → Proxy" and manually turn off "Use a proxy server," then relaunch the client normally.
• Multiple proxy apps running at once: If two proxy apps both set the system proxy, whichever started last overwrites the other, causing erratic behavior. Keep one and fully quit the rest (check the system tray).
• No network after sleep/wake: Occasionally happens in TUN mode — toggle TUN off and on to rebuild the virtual adapter.

↑ Back to chapter list

4.1Download and chip identification

Go to the download page's macOS section. Clash Plus is the top pick; alternatives are Clash Verge Rev and FlClash. ClashX Meta is discontinued and archival only. Before downloading, check your chip: click the Apple menu top-left → "About This Mac" — if "Chip" shows an Apple M-series, use the Apple Silicon build; if it shows an Intel processor, use the Intel build. An Apple Silicon Mac can run the Intel build via Rosetta, but with extra memory and power overhead — not recommended.

4.2Installation and handling Gatekeeper prompts

1. Open the downloaded dmg image, drag the app icon into the Applications folder, then eject the image.
2. On first launch, don't double-click — instead right-click (or Control-click) the icon → "Open," then click "Open" again in the dialog. This is the standard way to bypass Gatekeeper's first-run block for apps not distributed via the App Store.
3. If you see "The app is damaged and can't be opened," the downloaded file has usually been flagged with a quarantine attribute. After confirming the installer came from this site's download page, run the following in Terminal to remove the quarantine flag, then reopen the app:

sudo xattr -rd com.apple.quarantine /Applications/ClashPlus.app

Replace the path with the actual installed app name. Only run this command on apps whose source you've confirmed is trustworthy — that's the precondition for using it.

4.3Importing a subscription

Same steps as Windows: go to the subscriptions page → New → paste the link → confirm the download. Most macOS clients live in the menu bar and keep running after the main window is closed; click the menu bar icon if you can't find the window. After importing, pick a node on the proxies page — the policy group structure matches the proxy-groups in the config file one to one.

4.4System proxy and authorization

The first time you flip the "System Proxy" toggle, the system will pop up an authorization dialog asking for your password — the client needs permission to write the "Web Proxy (HTTP)," "Secure Web Proxy (HTTPS)," and "SOCKS Proxy" entries in the network settings. Once authorized, it stays valid long-term. To verify: check "System Settings → Network → [current network] → Details → Proxies" and confirm all three point to 127.0.0.1 and the client's port; or run scutil --proxy in Terminal — HTTPEnable should read 1 with a matching port.

4.5TUN mode

Enabling TUN on macOS requires the client to install a privileged helper or system extension, triggering one or two system-level authorizations on first enable (entering your password, and on some macOS versions manually "allowing" the blocked extension under "System Settings → Privacy & Security"). Once enabled, running ifconfig | grep utun in Terminal shows a new utun interface. As with Windows, command-line programs and some client software that don't read the system proxy need TUN to be proxied; if you only use a browser, the system proxy is already enough and TUN isn't necessary.

4.6macOS-specific issues

• Proxy stops working after a major OS upgrade: Upgrades can reset network settings or revoke extension authorization. Symptom: the toggle is on but traffic isn't proxied. Fix: turn the system proxy toggle off and back on to force it to rewrite the setting; TUN users should re-allow the extension under "Privacy & Security."
• Menu bar icon squeezed out: On notch-equipped models, menu bar space is limited and the icon can get hidden, making it look like the app isn't running. Reopen the app from Applications in Finder, or reduce the number of persistent menu bar items.
• Proxy set on only one interface when both Wi-Fi and Ethernet are active: The system proxy is configured per network service; if switching interfaces breaks the proxy, toggle the system proxy off and on to have the client rewrite it for the current interface.
• Work devices: MDM-managed devices may block installing system extensions, so TUN can't be enabled — in that case, the system proxy is the only option.

↑ Back to chapter list

5.1Choosing a client

Go to the download page's Android section. Clash Plus is the top pick; alternatives are Clash Meta for Android (often called CMFA in the community, full-featured with detailed settings), FlClash (intuitive UI, good for first-timers), and Surfboard. Most APKs target arm64-v8a, which covers virtually every mainstream device since 2016; if you see "There was a problem parsing the package" or "not compatible with this device," it's usually an architecture mismatch — try the armeabi-v7a or universal build instead.

5.2Installing the APK

1. Download the APK file in your browser, then tap it to install.
2. The system will block it with "Install unknown apps not allowed" — tap "Settings" in the prompt to jump straight to enabling "Allow from this source" for your browser; the manual path is "Settings → Apps → Special app access → Install unknown apps."
3. Go back and continue the install. Some manufacturer OS layers (MIUI, ColorOS, etc.) will add another "risky app" confirmation — just choose to continue; this is a standard prompt for any APK not from an app store.

5.3Importing a subscription

Open the app, go to the "Profiles" or "Subscriptions" page, tap New in the bottom right, choose the "URL" type, paste the subscription link, and save — the app downloads the config immediately. Long-press or open the subscription entry to set an auto-update interval; 12 or 24 hours is recommended. After importing, return to the home screen and the profile entry should appear checked/active.

5.4Starting the proxy: VpnService authorization

Android has no desktop-style "system proxy toggle" — the client uses the system's VpnService interface to set up a local VPN tunnel that intercepts traffic, equivalent to TUN mode on desktop. The first time you tap the start button on the home screen, the system pops up a "Connection request" dialog — you must tap "OK"; once authorized, a key-shaped VPN icon appears in the status bar, indicating it's running. Only one app can occupy VpnService at a time, so any other VPN-type app must be disconnected first. To verify: go to the "Proxies" page and run a latency test on a policy group — a returned value means the link is working.

5.5Android-specific issues

• Killed in the background: Aggressive battery-saving policies on many OEM Android skins are the number-one issue, showing up as the proxy dropping after the screen has been off a while. Fix: set the client's battery policy to "Unrestricted / Allow background activity" in system settings, and lock the app in the recents list; the menu names differ by manufacturer, but the idea is always "battery optimization whitelist + allow auto-start."
• Private DNS conflicts: If "Settings → Network → Private DNS" specifies a DoT server, DNS queries bypass the client and routing can misbehave. Set it back to "Automatic."
• Per-app proxying: The client's "App control" feature supports an allowlist (only listed apps are proxied) or a blocklist (listed apps are excluded). If a banking app is sensitive to VPN environments, add it to the bypass list.
• Always-on VPN: "Settings → VPN" lets you enable "Always-on VPN" and "Block connections without VPN" for the client — the former improves persistence, the latter cuts all network access if the proxy drops; weigh the trade-off as needed.

↑ Back to chapter list

6.1Getting the client

On iOS, use Clash Plus (App Store page), with the official site at clashplus.io. Search for it in the App Store or open the store page directly to install; updates are handled automatically by the store, no manual version tracking needed.

6.2First launch and VPN configuration authorization

The first time you launch the app and attempt to connect, it will request to add a VPN configuration; the system prompt requires you to tap "Allow" and verify with your passcode or Face ID. Once authorized, an entry appears under "Settings → General → VPN & Device Management → VPN." This step only happens once; connecting and disconnecting afterward is done from within the app or the VPN toggle in Settings.

6.3Importing a subscription

Go to the app's profiles/subscriptions page, create a new one and paste the subscription link, then activate it once the download finishes. If you copy the link in Safari and switch back to the app, it will sometimes auto-detect the clipboard and ask whether to import — just confirm. Subscriptions also support auto-update, with the interval adjustable in the subscription entry's settings.

6.4Connecting and daily use

Tap the connection toggle in the app; a VPN badge in the status bar means it's running. Node switching, policy group selection, and latency tests all happen in-app, with the same logic as desktop: policy groups map to the proxy-groups in the config file, and in rule mode you just need to pick the exit within the "Proxy Select" group. iOS's network extension has a memory cap, so subscriptions with a very large number of nodes may fail to connect on low-memory older devices — ask your provider for a trimmed-down subscription in that case.

6.5iOS-specific issues

• Switching profiles doesn't take effect: After activating a new profile, disconnect and reconnect so the network extension loads the new file.
• Brief drop when switching between Wi-Fi and cellular: The VPN tunnel rebuilds when the network interface changes, causing a few seconds of dropped connectivity — this is normal, and the app reconnects automatically.
• Leftover old VPN configurations: Devices that have used several proxy apps over time can accumulate multiple entries under "VPN & Device Management" — delete entries for apps you no longer use to avoid the system switching between the wrong VPN configs.
• Low Data Mode: With "Low Data Mode" enabled on cellular, background activity is restricted and subscription auto-update may be delayed — update manually if needed.

↑ Back to chapter list

7.1Desktop client installation

For desktop environments, Clash Verge Rev is recommended (deb and rpm packages available), with FlClash as an alternative. On Debian/Ubuntu, install the deb package with:

sudo dpkg -i clash-verge-rev_amd64.deb
sudo apt-get install -f   # If dependencies are missing, this completes the install

On Fedora and other rpm-based distros, use sudo rpm -i or sudo dnf install ./package-name.rpm. Installers are available on the download page's Linux section — be sure to pick amd64 vs. arm64 correctly. After installing, launch from the app menu; importing a subscription works the same as other desktop platforms: subscriptions page → New → paste the link → download → pick a node.

7.2System proxy: desktop environment vs. terminal

On Linux, "system proxy" is a desktop-environment-level setting — GNOME and KDE each have their own, and the client's system proxy toggle typically only writes GNOME's gsettings or the KDE equivalent. The equivalent manual commands for GNOME:

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

Key distinction: terminal programs don't read desktop proxy settings — they only respect environment variables. To proxy your current terminal session temporarily:

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

Adding these to a shell config file (like ~/.bashrc) makes them persistent, but remember that when the proxy is off, those variables will break your terminal's network access — it's worth wrapping them in a pair of toggle functions. If you'd rather not manage environment variables at all, enabling TUN mode solves it once and for all.

7.3TUN mode and permissions

Creating a TUN device requires the CAP_NET_ADMIN capability. Clash Verge Rev offers a "Service Mode": install a privileged background service in settings (one sudo authorization required), after which the regular UI can toggle TUN with normal permissions. Without service mode, you can grant the capability bit directly to the core binary:

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

Once enabled, ip addr shows a new TUN interface with the default route pointing to it. If desktop users see "the TUN toggle turns on and immediately flips back off," nine times out of ten the service isn't installed or authorization failed — reinstall the service and check the logs.

7.4Mihomo core: server and router scenarios

Headless servers and software routers run the Mihomo core directly. The core is a single executable, downloadable by architecture (amd64 / arm64 / armv7 / mips-softfloat) from the download page's core section; extract it into /usr/local/bin/, and put the config at /etc/mihomo/config.yaml (save the YAML returned by your subscription as this file). A minimal systemd unit example:

[Unit]
Description=Mihomo Daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/mihomo -d /etc/mihomo
Restart=on-failure
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_BIND_SERVICE

[Team]

The last line above is a placeholder — remove it when actually saving the file. Save it as /etc/systemd/system/mihomo.service, then run sudo systemctl daemon-reload && sudo systemctl enable --now mihomo to start it and enable it on boot, and use journalctl -u mihomo -f to follow the logs. The core has no UI — node switching is done through the external control interface (external-controller) enabled in the config, paired with a web dashboard; regular desktop users have no need to go this route, since GUI clients already cover everything they need.

7.5Connectivity verification

On Linux, the most direct check is having curl explicitly route through the local proxy:

curl -x http://127.0.0.1:7890 -sS -o /dev/null -w '%{http_code}\n' https://www.example.com

A 200 response means the whole chain — machine → core → node → target — is working; if it hangs or the connection is refused, first confirm the port (ss -lntp | grep 7890), then check the core logs for connection errors.

↑ Back to chapter list

8.1Still no internet after importing a subscription

Work through this fixed order without skipping steps: ① the system proxy or VPN toggle is actually on (check system settings on desktop, the status bar icon on mobile); ② the port shown in the client matches the one written to the system proxy; ③ the currently selected node returns a value on a latency test — if everything times out, switch nodes first; ④ the run mode is rule, not direct; ⑤ firewall or security software isn't blocking the core process. For step-by-step verification commands and finer-grained branches, see the article "Clash Connection Failure Checklist".

8.2Every node's latency test times out

Three likely causes, in order of probability: the subscription has expired or run out of traffic (check the expiration and traffic info on the subscription card, or log into your provider's panel to confirm); the local network is interfering with the node ports (try a different network, like a phone hotspot, as a control); or the latency test URL itself is unreachable (the test address can be changed in settings). A single node timing out is normal variance; the whole group timing out is what warrants investigation.

8.3A site goes out the wrong exit, or a rule isn't taking effect

First find the actual connection record for that site in the client's connections panel and check which rule it matched — that's the only reliable basis, don't guess. Common causes of wrong-exit routing: a custom rule placed after a broader one (rules stop at the first match, so anything after the MATCH fallback rule is dead code); a domain rule written as DOMAIN exact match when the actual traffic is to a subdomain, which should use DOMAIN-SUFFIX instead; or the target is accessed by bare IP, which domain rules never match — you need an IP-CIDR rule. For full examples of rule types and placement order, see "Clash Rule Priority Explained".

8.4DNS-related issues

Mainstream configs default to fake-ip mode: the core returns a fake IP in a reserved range for proxied domains, with actual resolution happening on the exit side, which avoids local DNS poisoning and reduces resolution latency. There are two expected side effects: seeing addresses in the 198.18.x.x range from local ping or nslookup is normal; and a handful of LAN programs that rely on real IPs need their domains added to the fake-ip-filter exclusion list. Another category of issue is OS-level DNS settings bypassing the core entirely — Android's Private DNS and browser-built-in DoH both cause routing to misbehave, so switch them back to automatic/off first when troubleshooting.

8.5Subscription update fails

Handle it based on the type of failure. Request timeout: the subscription domain may itself now require a proxy to reach — enable "Update subscription through proxy" in the client settings and retry. Error response or empty content: the subscription link may have been reset — log into your provider's panel, copy the new link, and re-import. Download succeeds but reports a format error: the link is likely not in Clash format (but for some other client) — ask your provider for the Clash subscription URL, or confirm the correct format option is selected in their panel.

8.6Still stuck?

This chapter covers the most common configuration-level issues; for more Q&A organized by category, see the FAQ page (basics / setup / usage tips / troubleshooting), and every protocol and feature name mentioned throughout has its own entry in the glossary. When describing an issue, include three things: platform and client name, run mode, and the matched rule from the connections panel — most issues can be pinpointed from those alone.

↑ Back to chapter list