Clash Handbook: Nine Stages from Zero to Pro
This is the most in-depth document on the site: it moves from core concepts all the way to router deployment, progressing stage by stage, with each chapter readable on its own. If you just want to get connected within ten minutes, start with the quick-start tutorial instead — it's the "follow along and you're connected" path. This handbook answers the "why" and "what else can be configured" questions the tutorial doesn't have room for. The two pages complement each other: run through the tutorial first, then come back here to go deeper chapter by chapter.
- Nine Chapters · Step by Step
- Every Platform Covered
- Ready-to-Use Config Samples
Core Concepts: How the Core, Client, Config, and Subscription Fit Together
Before you install anything, spend a few minutes getting these four terms straight — you'll see them again and again in every chapter that follows. Once this chapter clicks, any difference between client UIs will make sense on its own.
Clash Is a Toolchain, Not a Single Program
What people casually call "Clash" is actually three layers. At the bottom sits the core, a command-line program written in Go that listens on ports, parses rules, and forwards traffic. In the middle is the config file, a YAML document that tells the core which ports to open, which nodes exist, and which traffic should go where. On top is the client — the GUI app that bundles the core and handles config management, node switching, and the system proxy toggle for you. The mainstream core in today's ecosystem is mihomo (a continuation of the Clash Meta core), and every platform client on this site's download page is built on it. In other words, different clients are just different "shells" — the underlying rule syntax and behavior are the same, which is exactly why this handbook applies across clients.
Subscriptions: Config Files Hosted Remotely
A subscription is essentially just a URL. Visiting it returns a complete Clash config. Your provider writes node info and recommended rules into that config and hosts it on a server; you paste the URL into your client to import it. When the provider updates its nodes, one refresh of the subscription syncs everything — no manual text editing required. Subscription links typically embed an identity token, so leaking one is equivalent to handing your account to someone else. Chapter 4 covers importing and safekeeping in detail.
Proxy Protocols: How Each Node Transports Traffic
In the proxies section of a config file, every node declares its protocol type. Common ones include Shadowsocks (simple structure, the oldest around), VMess and VLESS (V2Ray-family protocols with various transport disguises), Trojan (mimics TLS traffic), and Hysteria2 (QUIC-based, performs well on poor networks). As a user you don't need to dig into protocol internals — the provider decides the protocol and writes it into the subscription, and any client works as long as its core supports it. The mihomo core supports all of the above.
The Full Path of a Single Request
Putting the whole flow together: an app makes a request → the traffic enters one of Clash's inbound ports (the system proxy or the TUN virtual adapter) → the core resolves the domain if needed → it matches the rules top to bottom → the matching rule points to a proxy group or DIRECT/REJECT → traffic exits through that outbound. Chapters 5, 6, and 7 map onto the "inbound," "rule matching," and "takeover method and DNS" stages of this chain respectively — feel free to come back to this map while reading them.
Choosing a Client: Pick the Right Build for Your Platform
Every platform has more than one client to choose from, but for most users the decision is quick. The table below matches the package list on the download page, listing a primary and a fallback pick per platform.
| Platform | Primary Pick | Alternatives | Notes |
|---|---|---|---|
| Windows | Clash Plus | Clash Verge Rev / FlClash / Clash Nyanpasu | Clash for Windows is unmaintained and kept only as an archive |
| macOS | Clash Plus | Clash Verge Rev / FlClash | ClashX Meta is unmaintained; existing users can keep using it |
| Android | Clash Plus | Clash Meta for Android / FlClash / Surfboard | VPN permission is required after install |
| iOS | Clash Plus (App Store) | — | Installed via the App Store; see the iOS section of the download page |
| Linux | Clash Verge Rev | FlClash | A deb package is provided; on servers you can run the core directly |
Why Clash Plus Comes First
Clash Plus is currently the only option that covers Windows, macOS, Android, and iOS with a consistent interface and workflow across all of them: whatever you learn about subscription management, node switching, and mode selection on desktop carries straight over to mobile without relearning anything. It bundles the mihomo core and keeps it current with releases, ships a fully localized interface, and has the lowest learning curve for anyone new to Clash. Users with multiple devices especially benefit from standardizing on one client everywhere, since there's only one interface to remember when troubleshooting.
Where the Alternatives Fit
Clash Verge Rev and FlClash are both actively maintained open-source clients: the former is feature-rich on desktop, supports config overrides and script extensions, and suits users who like tinkering with their setup — it's also the recommended pick for Linux desktops. The latter runs on Windows, macOS, Android, and Linux with a minimal interface. Clash Nyanpasu is Windows-only. As for Clash for Windows and ClashX Meta, both are unmaintained and no longer receive core or security updates; the download page keeps them archived only to ease migration of old configs, and new users shouldn't start with either one. For background on why they stopped receiving updates, see the related discussion in this site's articles.
Once you've settled on a target, head to the matching section of the download page: Windows client, macOS client, with the rest further down the same page.
Installation: What to Watch for on Each of the Five Platforms
Installing isn't complicated, but each platform has one system quirk that tends to trip people up. This chapter walks through them platform by platform — jump to the section that matches your device.
Windows
Run the downloaded installer and follow the wizard. Two things to expect: first, Windows SmartScreen may pop up a "Windows protected your PC" warning — this is the standard prompt for executables with a low download count, so click "More info" → "Run anyway" to continue. Second, avoid installing to a path with Chinese characters or spaces, since some core features (like service mode) are sensitive to the path. On first launch, the client parks an icon in the system tray permanently; closing the main window doesn't quit the app, and toggling the proxy afterward happens through the tray or the main window. If you're planning to use TUN mode from Chapter 7, it helps to install the system service ahead of time from Settings so the core can run with sufficient privileges.
macOS
Open the dmg image and drag the app icon into the Applications folder. On first launch, Gatekeeper may flag it for developer verification; if it's blocked, go to System Settings → Privacy & Security and find "Open Anyway" near the bottom of the page. The first time the client enables the system proxy or TUN, macOS will ask for authorization to install a network extension or change network settings, requiring an admin password to proceed — this is normal macOS permission flow, and declining means the proxy simply won't take effect. Apple Silicon and Intel chips need different installer packages, both listed separately on the download page; check your chip type under "About This Mac" to pick the right one.
Android
Installing the apk may prompt you to allow "install from unknown sources" — grant that once for your browser or file manager and move on. The first time you start the proxy, the system will show a VPN connection request that you must allow — the Android client takes over traffic through VpnService, and denying this permission means it simply can't function. It also helps to whitelist the client from battery optimization (Settings → Battery → Unrestricted); otherwise some manufacturers' systems will kill background apps once the screen turns off, which shows up as "the proxy drops after the phone sits idle for a bit."
iOS
On iOS, Clash Plus is installed through the App Store; the storefront link and instructions are in the iOS section of the download page. The first time you start the proxy, iOS will ask to add a VPN configuration — allow and authenticate once, and toggling afterward won't require repeating that step.
Linux
Taking a deb package as the desktop example, download it and run this in a terminal:
sudo apt install ./clash-verge-rev_amd64.debUsing apt install instead of dpkg -i resolves dependencies automatically. After installing, launch it from the app menu; if you use TUN mode, the client will walk you through installing a privileged service process. Servers or headless environments don't need a GUI client at all — just run the mihomo core directly, as covered in Chapter 9.
Subscription Import: Getting Nodes into Your Client
Right after installing, the client's node list is empty — nodes come from your provider through a subscription. This chapter covers importing, updating, and the three most common failure modes.
Three Ways to Import
The most common is URL import: copy the subscription link from your provider's user panel (something like https://sub.example.com/token/clash.yaml), open the "Profiles" or "Subscriptions" tab in your client, tap New/Import, paste the link, and confirm. The client immediately requests that URL, downloads the config, and lists every node. Second is clipboard import: some clients detect a subscription link on your clipboard and offer to import it directly — functionally identical to URL import. Last is local file import: if you already have a YAML config on hand (say, one you maintain yourself, covered in Chapter 9), you can load it as a file. This kind of config won't auto-update; any changes have to be made by hand.
How Updates Work
Subscriptions imported via URL support updating: tap the refresh button on the subscription entry, and the client re-requests the URL and replaces the local config wholesale with whatever comes back; most clients also let you set an auto-update interval (commonly 12 or 24 hours). If your provider changes node addresses, one subscription refresh restores access — when "every single node suddenly times out," refreshing the subscription is always the first move. One thing to keep in mind: an update replaces the entire file, so any manual edits made directly inside the subscribed config get wiped out. Persistent customizations should go through the client's override feature or a separate local config instead.
Three Reasons Imports Fail
First, an incomplete copy: subscription URLs are usually long, and forwarding them through a chat app can truncate them or insert a line break — if it fails, go back to the provider's panel and re-copy. Second, network access: some subscription servers themselves require certain network conditions to reach, so try switching networks and retrying. Third, a format mismatch: subscriptions come in Clash format and other formats, and a "parse failed" error usually means you grabbed a non-Clash link — provider panels typically offer multiple format links, so pick the one labeled Clash.
Heads up: a subscription link embeds your identity token, so anyone who gets hold of it can burn through your traffic allowance. Don't post it publicly, and always redact it in screenshots. If you suspect a leak, reset the subscription address from your provider's panel.
Once the import succeeds, you're ready for your first connection: pick a node group, test latency, enable the proxy, and verify it works — the main flow is on the tutorial page's connection step, and a deeper breakdown of latency numbers and verification methods is in the article "The Full Flow of Connecting to Clash for the First Time."
Proxy Modes & Ports: Where Traffic Enters and How It's Routed
Once a node is connected, two things shape your experience: which mode the core uses to decide where traffic goes, and which entry point hands system traffic to the core.
Three Operating Modes
| Mode | Behavior | When to Use |
|---|---|---|
| Rule | Matches rules one by one and routes direct or through the proxy based on the hit | Everyday default; splits domestic and international traffic automatically |
| Global | Ignores rules; all traffic goes through the currently selected node | Temporary troubleshooting, or when a site must go through the proxy |
| Direct | All traffic bypasses the proxy entirely | Temporarily disabling the proxy while keeping the client running |
You should stay in Rule mode almost all the time: local traffic goes direct for speed, and traffic outside mainland China gets routed through the proxy by rule. Global mode is a troubleshooting tool, not a daily setting — leaving it on long-term means even local traffic detours through a node, costing you both speed and quota. The exact spot to switch modes is on the tutorial page's mode selection step.
Inbound Ports
The core receives traffic by listening on local ports, and the port section at the top of the config controls this behavior:
mixed-port: 7890 # Combined HTTP + SOCKS5 port, recommended as your single entry point
allow-lan: false # Whether other devices on the LAN can connect
mode: rule # Default mode on startup
log-level: info # Log level: silent / error / warning / info / debug
external-controller: 127.0.0.1:9090 # RESTful control API for dashboard-style toolsmixed-port is the current standard approach: the same port accepts both HTTP and SOCKS5 proxy requests, replacing the older config's separate port and socks-port entries. 7890 is a conventional default rather than a requirement — if it's already taken by another program (the client log will report a bind failure), switch to any free port, just remember to update the system proxy settings to match. Turning on allow-lan lets phones and TVs on the same network point their gateway proxy at this machine's IP and port to share the proxy exit; keep it off on public networks.
System Proxy: Getting Apps to Hand Over Their Traffic
Flipping on the "system proxy" toggle points the OS's proxy setting at 127.0.0.1:7890; browsers and other apps that respect the system proxy setting will automatically forward requests to the core. That's also its limit: only apps that "respect the system proxy" get covered — plenty of command-line tools and some desktop software ignore it entirely, which is exactly the gap TUN mode (Chapter 7) closes. If you've enabled the system proxy but your browser or terminal still isn't going through it, check those two separately using the steps in "Troubleshooting a Clash System Proxy That Isn't Working."
Rule Routing: The Config File's Core Mechanism
All of Rule mode's behavior comes down to two sections in the config: proxy-groups and rules. Your subscription's config already has both written out — once you understand their syntax, you can read exactly what your subscription is doing, and start customizing it yourself. For a full section-by-section breakdown of the config file, see "A Detailed Walkthrough of the Clash Config File Structure"; this chapter focuses on the routing mechanism itself.
Proxy Groups: Organizing Nodes into Selectable Strategies
Rules never point straight at a node — they point at a proxy group, and the group decides which node inside it gets used. Four group types come up most often: select for manual picking, where you click a node in the UI; url-test for automatic latency testing, periodically pinging a test URL and picking the lowest-latency node; fallback for failover, trying nodes in list order and moving to the next when one fails; and load-balance, which spreads connections across multiple nodes. Example:
proxy-groups:
- name: Node Select
type: select
proxies:
- Auto Test
- HK Node
- JP Node
- DIRECT
- name: Auto Test
type: url-test
url: https://www.example.com/generate_204
interval: 300
proxies:
- HK Node
- JP NodeNesting an auto group inside a manual group like this is common: leave it on "Auto Test" for everyday convenience, and switch to a specific node manually whenever you need a fixed exit (logging into a region-sensitive service, for instance). interval is in seconds; 300 means it re-tests every five minutes.
Rules: Top to Bottom, First Match Wins
The rules section is an ordered list, each line in the format "type,value,outbound." The core checks each connection against these entries from the top, and stops at the first match — nothing below it gets considered. That means order is priority: specific rules go near the top, catch-all rules go last. The most common types:
DOMAIN: an exact match on a full domain;DOMAIN-SUFFIX: matches a domain and all of its subdomains — the one you'll use most;DOMAIN-KEYWORD: matches if the domain contains a keyword — broad reach, use with care;IP-CIDR: matches by IP range, often paired withno-resolveto avoid triggering resolution for what's really a domain-based request;GEOIP: matches by IP geolocation —GEOIP,CN,DIRECTis the standard way to say "route mainland China IPs direct";MATCH: matches unconditionally, and must be the last entry and nothing else.
rules:
- DOMAIN-SUFFIX,example.com,Node Select
- DOMAIN-KEYWORD,tracker,REJECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- GEOIP,CN,DIRECT
- MATCH,Node SelectBesides proxy group names, there are two built-in outbound values: DIRECT for a direct connection and REJECT to refuse the connection outright (often used to block telemetry domains). When reading the rules bundled in a subscription, focus on the overall shape: the bulk of it categorizes domains/IPs for various services, the second-to-last entry is usually a GEOIP direct rule, and the final MATCH entry hands everything else to the main selector group.
Tip: to force a specific site through a particular exit, you don't need to rewrite the whole config — just add a DOMAIN-SUFFIX entry at the very top of the rules list, taking advantage of "first match wins" to override everything below it. Add it through the client's override feature so a subscription update doesn't wipe it out.
TUN & DNS: Taking Over All Traffic
Chapter 5 covered the system proxy's boundary: it can't reach programs that ignore proxy settings. TUN mode solves this at the network layer, and it's the dividing line for advanced desktop use.
How TUN Works
With TUN enabled, the core creates a virtual network adapter on your system and adjusts the routing table to make it the default route. From then on, every network flow — whether or not the app in question honors proxy settings — hits this virtual adapter first and gets processed by the core according to your rules. In effect, it's a device-level takeover: command-line tools, games, and system components all fall under your routing. The tradeoff is elevated privileges: Windows requires installing a core component in service mode, macOS requires authorizing a network extension, and Linux requires a privileged service — every client's settings page offers a one-click installer for this. Once TUN is on, turn off the system proxy toggle; having both active at once serves no purpose and can create a routing loop.
DNS Takeover and Fake-IP
In TUN mode, DNS has to be handled by the core — otherwise you end up with a leak where "traffic goes through the proxy but domain resolution happens locally in plaintext," and domain-based rules may also stop working correctly. The dns section of the config controls this:
dns:
enable: true
listen: 0.0.0.0:1053
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- "*.lan"
- "+.local"
nameserver:
- https://doh.example.com/dns-queryenhanced-mode takes two values. redir-host follows the traditional path: it resolves the domain for real first, then forwards based on that result — straightforward, but adds an extra resolution delay and the result can be tampered with. fake-ip instead returns a made-up address from a reserved range (198.18.0.0/16 by default) the instant an app queries a domain, and the core keeps a mapping of "fake IP ↔ domain"; when the app connects to that fake IP, the core matches rules against the original domain and forwards accordingly. The upside is a fast response and rule matching that's always based on the real domain; the downside is that a handful of scenarios relying on real IPs (LAN device discovery, some intranet services) can misbehave — add the relevant domains to fake-ip-filter to exclude them. For nameserver, use encrypted DNS (DoH/DoT) to avoid upstream resolution being tampered with.
Heads up: after switching between fake-ip and redir-host, your OS and browser may still be caching the old resolution result, which shows up as some sites briefly refusing to load. Run ipconfig /flushdns on Windows, or just restart your browser/device, to clear the cache.
When You Actually Need TUN
The test is simple: if everything you need happens inside a browser, the system proxy is enough and there's no reason to take on TUN's extra permission complexity. But once terminal commands, dev tools, games, or other programs that ignore the system proxy enter the picture, TUN is a far cleaner solution than setting proxy environment variables app by app. To verify TUN is working, fire off a request from a terminal and check the exit IP — the method is on the tutorial page's verification step.
Maintenance: Updates, Logs, and Troubleshooting Reference
Once your setup is working, there isn't much day-to-day upkeep — but getting it right avoids most emergency troubleshooting.
Three Things to Keep Updated
Subscription: turn on auto-update, or get into the habit of manually refreshing every few days — node changes on the provider's end only sync after an update. Client and core: client updates usually ship with core updates, and newer cores keep up with evolving protocol and rule capabilities, so it's worth upgrading promptly when your client flags a new version. Geo database: the geolocation database that rules like GEOIP rely on — most clients offer a one-click update, and letting it go stale can cause some IPs to be misattributed.
Learning to Read the Logs
The client's log/connections panel is the most direct troubleshooting tool: the connections page shows which rule each active connection matched and which exit it took — questions like "why did this site go direct" are answered at a glance. The log page records core events, and startup failures, port conflicts, and subscription fetch errors all leave clear traces there. For a breakdown of each panel's layout, see "A Quick Tour of the Clash Client Interface." Before troubleshooting anything, temporarily bump the log level up to debug for full detail, then set it back to info once resolved.
Common Issues at a Glance
| Symptom | Check First |
|---|---|
| Every node times out | Refresh the subscription first; confirm your own network works; then try a different node group |
| Browser isn't proxied | Is the system proxy toggle on; does the browser have an extension overriding proxy settings |
| Terminal isn't proxied | Terminals ignore the system proxy — set the http_proxy environment variable or switch to TUN mode |
| Client fails to start with a port error | 7890/9090 is already in use — change mixed-port or quit the conflicting program |
| Some sites won't load, others fine | Check which rule the domain matched in the connections panel; try a different node; flush DNS cache after switching fake-ip |
| Connection drops when the phone screen locks | Add to Android's battery optimization whitelist; confirm the VPN permission hasn't been revoked by the system |
Backups and Launch-on-Startup
It's worth keeping a copy of your subscription URL, override scripts, and any self-maintained local config in a password manager or personal notes — that way switching devices or reinstalling takes minutes to restore. On desktop, turn on "launch at startup" and "auto-connect" in settings; paired with TUN or the system proxy, no manual step is needed after a reboot. Server-side autostart is covered in the next chapter.
The Advanced Path: From Using a Config to Managing One
By this point, everything the client can offer has been covered. The advanced direction is taking control of your config back into your own hands, roughly in three steps.
Step 1: Overrides and Manual Tweaks
Since a subscription update replaces the whole config, the right way to make persistent customizations is through the client's override mechanism: write your changes (extra rules, DNS tweaks, a different port) as an independent snippet that the client merges in automatically after every subscription update. Once you're comfortable with Chapter 6's syntax, you can go a step further and maintain an entirely hand-written local config: pull the proxies section from your subscription and organize everything else to your own needs. The biggest pitfall writing YAML is indentation — levels only use spaces, fields at the same level must align exactly, and one stray tab is enough to break the whole config's parsing. See the config structure walkthrough for details.
Step 2: Running the Core Directly
Running the mihomo core directly, without a GUI, suits servers and unattended long-term setups. Grab the binary for your architecture from the core section of the download page, extract it, and point it at a config directory:
# Place your config at ~/.config/mihomo/config.yaml
./mihomo -d ~/.config/mihomo
# Validate syntax only, without starting
./mihomo -t -d ~/.config/mihomoThe -t flag is worth remembering: validating a config right after editing it is far more efficient than digging through logs after a failed startup. On Linux, pair this with a systemd service unit for launch-on-boot and automatic restart on crash; with external-controller enabled, you can also use a web dashboard to view connections and switch nodes remotely, which makes up for the lack of a GUI.
Step 3: Router and Bypass-Gateway Deployment
Running the core on a router or a bypass gateway means every device on the home network — including TVs and consoles that can't run a client at all — gets routed traffic automatically, with zero configuration on the device side. This path involves hardware selection, transparent proxying, DNS takeover, and autostart supervision as a full topic of its own; for the tradeoffs between main-router and bypass-gateway topologies and a full deployment overview, see "Running the Clash Core Directly on a Router or Bypass Gateway: A mihomo Deployment Overview."
Suggested order: get comfortable with Rule mode and TUN on desktop first (Chapters 5 through 7), then try overrides and hand-written configs (Step 1 of this chapter), and only then consider running the core directly or deploying on a router (Steps 2 and 3). Each step builds on the troubleshooting experience from the one before it — skipping ahead just turns simple problems into complicated ones.
Download Clash
Every platform client covered in this handbook is available on the download page — Clash Plus is the top pick for a consistent experience across devices. For your first connection, pair it with the quick-start tutorial.