Clash Setup Guide for All Platforms

General Prep Work

Whichever platform you're on, there are three things to sort out before your first setup: pick a client, get your subscription link, and understand the basic structure of a config file. These three are identical across every platform, so we cover them once here and won't repeat them in the platform chapters below.

Choosing a Client

Clash is an open-source ecosystem, and the same config file works across different clients. Recommended picks for each platform are listed below; get all installers from the Download page, and see the blog post Comparing the Main Clash Clients for a detailed breakdown of the differences.

Subscription Links

A subscription link is an HTTP(S) address provided by your service, pointing to a list of nodes and rules that Clash can parse. The client fetches it at a fixed interval and picks up node updates automatically. Before you start, confirm two things: first, the link is complete, starts with https://, and hasn't been truncated or had line breaks added by a chat app; second, treat the link as a sensitive credential — anyone who has it can use your traffic quota, so don't post it in public groups or leak it in screenshots. For what a broken or malformed link looks like and how to fix it, see the Config FAQ chapter.

Basic Structure of the Config File

A Clash config file is a YAML document, usually generated from a subscription. Understanding its basic skeleton helps a lot when troubleshooting later. There are five core sections: inbound port, run mode, node list, proxy groups, and rules. Here's a minimal readable example:

mixed-port: 7890          # Shared inbound port for HTTP and SOCKS
allow-lan: false          # Whether to allow LAN devices to connect
mode: rule                # rule / global / direct
log-level: info
external-controller: 127.0.0.1:9090

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

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

rules:
  - DOMAIN-SUFFIX,github.com,Proxy Selector
  - GEOIP,CN,DIRECT
  - MATCH,Proxy Selector

Rules are matched top to bottom, and matching stops at the first hit; MATCH is the catch-all rule and must go last. For the detailed behavior of proxy group types like select, url-test, and fallback, see the blog post Proxy Group Types Explained; for definitions of individual fields, check the Glossary.

System Proxy vs. TUN Mode

Once started, the client just opens a proxy port on your machine — traffic doesn't flow into it automatically. There are two ways to route traffic in: system proxy and TUN mode. System proxy points the OS's HTTP/SOCKS proxy settings at the local port; it's simple but only affects apps that respect system proxy settings. TUN mode creates a virtual network adapter and intercepts all traffic at the network layer, covering command-line tools and games that ignore the system proxy, at the cost of requiring elevated system privileges.

Three Run Modes

The mode field in the config controls how the rule engine behaves. rule mode routes traffic rule by rule and is the everyday default; global mode sends all traffic through a single proxy group, useful for quickly testing a node; direct mode bypasses the proxy entirely, useful for checking whether an issue is actually proxy-related. Switching between the three modes and comparing results is one of the fastest ways to pin down a problem.

Windows Setup

Download and Install

Get the Clash Plus installer from the Windows section of the Download page; it requires Windows 10 64-bit or later. When you run the installer, SmartScreen may pop up "Windows protected your PC" — this is common for open-source software without a paid code-signing certificate. Click "More info" then "Run anyway" to continue. It's best to keep the default install path; if you use the portable version, avoid extracting it into a folder that requires admin rights (like manually unzipping under C:\Program Files), or writing the config will fail.

Import Your Subscription and First Connection

After the first launch, go to the Subscription (or "Profiles") page, paste your subscription link, and click Import. The client downloads the config and shows a list of nodes. Switch to the Proxies page, pick a node under the "Proxy Selector" group, then go back to the main screen and turn on the "System Proxy" toggle. Open a browser and visit a site covered by the rules — if it loads normally, the connection works. If every node shows a timeout, work through the five-layer checklist in the blog post How to Diagnose Node Timeouts.

System Proxy and Ports

The "System Proxy" toggle works by changing the address in Windows Settings → Network & Internet → Proxy to 127.0.0.1:7890 (the port depends on your client's settings). If the setting doesn't take effect after turning it on, first check whether another program is already using the port:

netstat -ano | findstr "7890"

If the output shows another process already listening on that port, change mixed-port in your client settings to a free value like 7891, restart the client, then turn on the system proxy again. Running multiple proxy apps at once causes them to overwrite each other's system proxy settings, so keep only one running.

TUN Mode and Service Mode

Creating a virtual adapter on Windows requires admin rights. Clients like Clash Verge Rev offer a "Service Mode": it installs a background service that runs with the system, so you no longer get a UAC prompt every time you toggle TUN. This is usually found under Settings → Service Mode → Install. After installing the service, turn on the TUN toggle — you'll see a new virtual adapter appear under Settings → Network Connections once it's active. With TUN on, it's best to turn off the system proxy toggle to avoid traffic passing through both layers.

Launch at Startup

Client settings usually have two toggles: "Launch at Startup" and "Silent Start". The first registers a startup entry; the second skips the main window and starts minimized in the tray. Turning both on, combined with a default subscription, means the last proxy state is restored automatically at boot with no manual steps. If auto-start fails, check whether the entry is disabled under Task Manager → Startup Apps.

Windows-Specific Issues

• UWP apps (installed from the Microsoft Store) don't allow loopback to a local proxy by default; some clients include a "UWP Loopback Exemption" tool — check the box for the relevant app to fix it.
• When the Windows Firewall prompt appears on first launch, check "Private networks" and allow it, or LAN devices won't be able to connect when allow-lan is enabled.
• After uninstalling old proxy software, the system proxy setting can be left pointing at a dead port, which looks like "no internet". Manually turning it off in the system proxy settings fixes it.

macOS Setup

Check Your Chip

Click the Apple menu at the top left → About This Mac: if the Chip field shows an Apple M-series chip, download the Apple Silicon (arm64) build; if it shows Intel, download the Intel (x64) build. Installing the wrong build will run through Rosetta translation on Apple Silicon — it works, but performance and power efficiency both take a hit, so get the right one. Builds are split by architecture on the macOS section of the Download page.

Install and First Launch

Open the dmg image and drag the app icon into the Applications folder, then launch it from Launchpad or the Applications folder. If you see "Cannot verify developer" the first time you open it, go to System Settings → Privacy & Security, find the notice for the app near the bottom of the page, and click "Open Anyway"; or right-click the app icon in Finder and choose "Open" — after confirming once, you can double-click to launch normally afterward.

Permissions: Network Extensions and Keychain

The first run of a macOS client triggers two or three permission prompts in a row, and each needs to be handled correctly or the client won't fully work:

1. Network Extension / Proxy Configuration prompt: click "Allow". This is required for system proxy and TUN to work — if you deny it, the client can only offer a local port.
2. Keychain Access prompt: enter your login password and click "Always Allow" instead of "Allow". Clicking "Allow" means the prompt reappears every time you launch the app.
3. Some clients also ask to install a privileged helper tool — enter your password once to confirm that too.

If you accidentally clicked Deny, you can fix it: go to System Settings → Network → VPN & Filters, and Privacy & Security → Full Disk Access, and manually re-grant permission to the client. For full screenshots and a step-by-step walkthrough, see the blog post Clash Client Permissions on macOS, Fully Explained.

System Proxy and Verification

After importing your subscription and picking a node, turn on the client's "Set as System Proxy" toggle. To verify it actually wrote to the system settings, run this in Terminal:

networksetup -getwebproxy Wi-Fi

If it outputs Enabled: Yes and the port matches your client, it's active. Note that macOS saves proxy settings per network service: Wi-Fi and wired Ethernet are two separate configurations. If the proxy stops working after switching network interfaces, it's usually because the client only wrote to one of the services — toggling the system proxy off and back on fixes it.

TUN Mode

Enabling TUN on macOS requires approving a system extension or creating the virtual adapter through a privileged helper, so the first time you turn on TUN you'll get another permission prompt. Once it's on, run ifconfig | grep utun in Terminal to see the new utun interface. Just like on Windows, turn off the system proxy toggle while TUN is on to avoid double-proxying.

macOS-Specific Issues

• After a major macOS upgrade, network extension permissions can get reset — the client runs fine but traffic doesn't go through the proxy. Just redo the permission flow.
• If the client crashes without resetting the system proxy, you can end up with "no internet after closing the app". Go to System Settings → Network → the relevant service → Details → Proxies, and uncheck it manually.
• If you have multiple Clash clients installed, don't run them at the same time — the system proxy gets repeatedly overwritten and behavior becomes unpredictable.

Android Setup

Choosing the Right Build

Mainstream phones from the last few years all use the arm64-v8a build; only some older or entry-level devices use armeabi-v7a. If you're not sure, try arm64 first, and switch to v7a if you get "There was a problem parsing the package" or "App not installed". Clash Meta for Android also offers a universal build — bigger, but no guessing needed. Builds are split by architecture on the Android section of the Download page.

Install and Import Your Subscription

After downloading the APK in your browser, install it — the system will ask to "Allow installation from unknown sources"; enable that permission for your browser (or file manager) in the settings page that pops up, then go back and continue installing. On first launch, go to the Profiles/Subscription page, create a new profile, paste your subscription link, and save — the client downloads and parses it automatically. Seeing nodes appear in the list means the import worked.

VPN Permission and Connecting

Android clients take over traffic through the system's VpnService. The first time you tap Connect, a "Connection request" dialog appears saying a VPN connection will be created — tap "OK". This only needs to happen once; a key icon in the status bar means the connection is active. After that, connecting and disconnecting is a one-tap action on the client's main screen. Android has no separate "system proxy" toggle — VpnService itself works like TUN mode on desktop.

Background Persistence and Battery Optimization

Heavily customized Android skins are often aggressive about killing background processes, which is the number one cause of "it disconnects on its own" on Android. Work through these:

• System Settings → Battery → find the client and set battery optimization to "Unrestricted" or "No optimization".
• On skins with an "Autostart Manager" (like MIUI, EMUI, etc.), grant autostart permission to the client.
• Lock the client in the Recent Apps screen (swipe down or long-press the card, depending on the manufacturer) so it doesn't get killed by "clear all".

Per-App Proxy

The "Access Control" option in the client's network settings supports routing by app: whitelist mode sends only checked apps through the proxy, and blacklist mode excludes checked apps from the proxy. Banking apps are sensitive to proxy environments, so blacklisting them avoids false fraud flags; blacklisting games can cut unnecessary latency. Reconnect once after changing the per-app list for it to take effect.

Android-Specific Issues

• When system "Private DNS" (Settings → Network → Private DNS) is set to a fixed provider, DNS queries bypass the client's fake-ip system, which can break some rules. Set it to "Automatic" or turn it off.
• The system only allows one active VPN connection at a time, so other VPN apps will knock each other out — that's expected system behavior, not a bug.
• On some devices, Data Saver combined with a VPN restricts background traffic — if something's off, check your system's battery and data-saver settings first.

iOS Setup

Install from the App Store

On iOS, Clash Plus installs directly from the App Store: search "Clash Plus" in the store, or jump to its store listing from the iOS section of the Download page. The app's official site is clashplus.io, which is the reference for feature details and release notes. There's one universal version for iPhone and iPad.

Import Your Subscription

Open the app, go to the Subscription/Profiles page, tap Add, paste your subscription link, and save. Some versions can read the clipboard for a quick import: copy the link first, then open the app and confirm the prompt. Once imported, the node list appears on the Proxies page — pick one node as your current exit.

VPN Configuration and Authorization

The first time you tap Connect, the system shows ""Clash Plus" Would Like to Add VPN Configurations" — tap "Allow" and verify with your passcode or Face ID. Once granted, the system creates an entry under Settings → General → VPN & Device Management → VPN, and a VPN badge in the status bar confirms the connection is up. From then on, you can connect and disconnect either inside the app or from the VPN toggle in system Settings — both stay in sync.

Usage Notes

• After switching subscriptions or making major config changes, disconnect and reconnect once so the new config fully takes effect.
• If the system evicts the app from memory, the VPN tunnel is usually still held open by the system's network extension. If you notice a disconnect, just reopen the app and reconnect.
• Concepts like rule mode and proxy groups work exactly the same as on desktop, so the general config knowledge in this page's Prep Work chapter and the Glossary apply directly.

Linux Setup

Client Installation

For desktop use, Clash Verge Rev is recommended — it ships deb and rpm packages; FlClash offers a deb package. Get installers from the Linux section of the Download page; installing through your system's package manager resolves dependencies automatically:

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

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

If installation complains about missing dependencies like libwebkit2gtk, run sudo apt update first and try again; the apt install ./package-name form (with the ./) handles dependencies for you, which is easier than dpkg -i.

System Proxy in Desktop Environments

On Linux, "system proxy" is implemented separately by each desktop environment. In GNOME, go to Settings → Network → Network Proxy, choose "Manual", and enter 127.0.0.1:7890 for HTTP/HTTPS (same for the SOCKS host); in KDE, configure it under System Settings → Network Settings → Proxy. A client's system proxy toggle usually only works for GNOME/KDE — for other desktop environments or terminal-only setups, 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

Add these to ~/.bashrc or ~/.zshrc to make them persistent. Note that environment variables only affect programs that read them — most browsers read desktop environment settings instead.

TUN Mode and Permissions

Creating a TUN device requires root privileges or the corresponding capability. Clash Verge Rev offers a service mode — after installing the system service, the service process creates the adapter with elevated privileges while the app itself runs unprivileged; just install the service and turn on TUN in the client's settings. If you're running the core manually, you can grant capability bits to the binary and run it as a regular user:

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

Servers: Running the Mihomo Core Directly

Headless servers or router setups don't need a GUI — run the Mihomo core directly. Put the core binary at /usr/local/bin/mihomo, place the config at /etc/mihomo/config.yaml, and manage it with systemd:

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

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

[Install]
WantedBy=multi-user.target

Save this as /etc/systemd/system/mihomo.service, then run sudo systemctl enable --now mihomo to start it and enable it at boot. Watch logs live with journalctl -u mihomo -f; once external-controller is enabled in the config, you can manage it remotely from any Clash dashboard. Core builds for every architecture are also on the Core section of the Download page.

Linux-Specific Issues

• Many distros ship systemd-resolved listening on port 53, which conflicts with setting dns.listen to 53 in your config. Move Clash's DNS listener to a port like 1053 instead, or adjust the resolved config.
• With a firewall (ufw/firewalld) enabled, allow-lan needs the corresponding port opened before LAN devices can connect.
• Under Wayland sessions, some clients' tray icons may not show up — this doesn't affect functionality, and you can reopen the main window from the application menu.

Config FAQ

Subscription Import Fails

Check these in order: whether the link is complete and hasn't been cut off by line breaks or spaces; open the link directly in a browser — if you get text content, the link itself is reachable; if what you download isn't YAML but some other format, the subscription isn't in Clash format and needs to be switched at the provider or run through a subscription converter. A few subscription servers check the request's User-Agent — importing with a different client or adjusting the UA in client settings gets around that.

All Nodes Time Out

Every node showing red doesn't mean the nodes are dead — it's usually a local connectivity problem. Check five layers in order: whether the subscription has expired → whether the local port is already in use → whether the system proxy toggle actually took effect → whether the node protocol matches the core → whether DNS is being tampered with. For how to check each layer and fix it, see the blog post How to Diagnose Node Timeouts.

Rules Don't Take Effect

The three most common causes, roughly in order of likelihood: first, mode isn't set to rule — under global or direct mode, the rule list plays no part at all; second, rule ordering — matching goes top to bottom and stops at the first hit, so a custom rule placed after a broader one never gets a turn; third, the traffic is already using a DNS-resolved IP, so DOMAIN-type rules can't match it — add an IP-CIDR rule or enable fake-ip. Remember to reload the config after editing rules.

DNS and fake-ip

DNS tampering can resolve domains to the wrong IP, showing up as "the node works but a few sites won't load". Enabling the fake-ip enhanced mode is recommended: the client first returns a fake IP from a reserved range, and the real resolution happens over the proxy — sidestepping local tampering at the source. Example config:

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

Under fake-ip mode, a few apps that depend on real IPs (LAN discovery, some games) can use fake-ip-filter to list domains that should get real resolution instead. See the "Network & DNS" section of the Glossary for related terms.

Port Conflicts

If another program is using the default inbound port 7890, the client may fail to start, or the system proxy ends up pointing at a dead port. The fix is always the same: change mixed-port to a free port, restart the client, and confirm the system proxy setting updates accordingly. Use netstat -ano on Windows or lsof -i :7890 on macOS/Linux to find the process holding the port.

YAML Syntax Errors

If you get "Failed to load config" after hand-editing, nine times out of ten it's a YAML syntax issue. Three rules to live by: use spaces for indentation only, two spaces per level, and never mix in tabs; always put a space after a colon; and quote the entire value if it contains a colon, a hash, or starts with a special character. After editing, run a syntax check with the client's "Validate Config" feature or mihomo -t -f config.yaml before loading it for real.

Subscription Update Strategy

Subscription content is maintained by your provider, and updates are how you get node changes. It's a good idea to turn on auto-update with a 24-hour interval; if you see widespread timeouts or an announcement says nodes have changed, update the subscription manually and test again. Note that "update subscription" overwrites any local edits to that config with the remote content — write custom rules in the override/merge config your client provides, not directly into the file generated from the subscription.