Clash Handbook: Zero to Mastery

Clash is a rule-driven network proxy tool. Its behavior boils down to one sentence: it reads a YAML config file, and based on the rules defined there, decides whether each network connection is sent out directly or handed off to a proxy node for forwarding. Understand that sentence, and every chapter that follows is just an expansion of it.

Kernel and Client

The word "Clash" actually refers to two different layers in everyday usage. The first is the kernel: a headless command-line program responsible for the actual traffic handling, rule matching, and protocol implementation. The original Clash kernel has been archived; the actively maintained successor in the community today is the mihomo kernel. The second is the client: the graphical shell around the kernel, handling subscription management, toggles, and log display—the human-facing side. Names like Clash Plus, Clash Verge Rev, and FlClash all belong to the client layer, and internally they drive the same family of kernel. This also explains a common question—why different clients can use the same subscription: the config file is written for the kernel, and the client is just the delivery vehicle. A full breakdown of the project lineage is in this note.

Four Terms You Can't Avoid

• Node (proxy): A usable proxy server—a proxies entry in the config, containing a server address, port, protocol, and credentials.
• Subscription: A URL hosted by your provider that returns a full config or node list when accessed. The client polls it periodically, and node changes sync automatically without editing any files by hand.
• Proxy group: A bundle of multiple nodes into one selectable unit, such as a "manual selection group" or "auto speed-test group." Rules point to a proxy group, not directly to a specific node.
• Rule: A single line declaring "match condition + exit," such as "domains ending in github.com go through the proxy group." Rules are matched top to bottom, and the first match wins.

The Full Journey of a Connection

A browser initiates a request, and the connection first enters the local port Clash is listening on. The kernel extracts the target domain or IP and compares it against the rule list from the top down. Once a rule matches, the connection is handed to the proxy group that rule specifies; the proxy group then determines the final node based on its own type (manual selection or auto speed-test); the data is forwarded through that node to the destination. All of this happens locally, in milliseconds. Every feature covered from here on—mode switching, rule writing, TUN—is just a change to the behavior of one segment of this journey.

Picking the wrong client won't cause any real damage, but it will waste your time. Choosing one only requires answering three questions: which OS you're on; whether you need TUN mode to take over all traffic; and whether the project is still maintained. That third question is the one people skip most often—an unmaintained client won't track kernel updates, so new protocols and rule types will simply be out of reach, and OS upgrades can introduce compatibility issues down the line.

Platform Quick Reference

A Few Selection Notes

Clash Plus covers all five platforms with a consistent interface and full subscription management—it's the safe default if you want something that just works, and it especially benefits users running multiple devices thanks to its consistent workflow. Clash Verge Rev, built on the mihomo kernel, offers the deepest configuration power and suits users comfortable editing YAML; it's also the top pick for Linux desktops. FlClash goes for a lightweight footprint, with low resource usage that works well on older machines or when running in the background constantly. Clash Nyanpasu is Windows-only, with a distinctive interface and features close to Verge Rev. Surfboard is a lightweight Android client focused on basic proxying rather than advanced features.

For a side-by-side score across four dimensions (system overhead, TUN support, subscription management, ease of use), see the comparison page for finer-grained conclusions; the blog's client selection notes add real-world usage scenarios. Once you've decided, head straight to the download page—installers for every platform are listed in the same order.

Installing itself isn't complicated, but every platform has one system-level checkpoint: a security prompt on desktop systems, and a VPN authorization step on mobile systems. Knowing what prompt to expect and which button to click ahead of time keeps you from getting stuck on step one.

Windows

Get the installer from the download page and double-click to run it. On first run, SmartScreen may pop up with "Windows protected your PC"—this is a generic warning for unsigned or low-download-count apps, not a virus alert. Click "More info," then "Run anyway" to continue. Keep the default install path; if you plan to use TUN mode later, follow the client's prompt to install the system service on first launch—authorize once, and it won't ask again.

macOS

Download the .dmg image, open it, and drag the app icon into the Applications folder. On first open, Gatekeeper will warn that the app was downloaded from the internet—choose "Open" to confirm. Watch the chip architecture: Apple Silicon machines (M-series) need the arm build, Intel machines need the x64 build; picking the wrong one runs through a translation layer with a noticeable performance hit. Enabling enhanced mode or TUN will prompt for your password to install a helper tool—that's a normal part of the authorization flow.

Android

When installing the APK, the system may warn "installation from unknown sources is blocked"—temporarily enable that permission for your browser or file manager in Settings. The first time you tap connect, a system dialog appears asking "XX wants to set up a VPN connection"—Android clients take over traffic through the system's VPN interface, and you must agree for it to work; this only shows up once. Some manufacturer skins aggressively kill background apps, so add the client to the battery optimization whitelist, otherwise the connection may get cut after the screen locks.

iOS

iOS distribution goes through the App Store—search for Clash Plus, or use the link on clashplus.io. On first launch after install, it will similarly request permission to add a VPN configuration; confirm in the system dialog and verify once with Face ID or your passcode. On iOS, the proxy operates at the system network layer, so every app follows the client's rules uniformly with no per-app setup needed. For a step-by-step screenshot walkthrough of first-time setup, see the blog's iPhone first-run notes.

Linux

For desktop distributions, the .deb package is recommended—install directly on Debian/Ubuntu:

sudo apt install ./clash-verge.deb
# If it reports missing dependencies:
sudo apt --fix-broken install

Fedora-based systems use the .rpm package with dnf install. On headless servers, download the mihomo kernel binary directly, extract it, and run it under systemd; the kernel download link is also in the kernel section of the download page.

Once the client is installed, it's empty—no nodes, no connection to anywhere. Node data enters the client through a subscription, which is the only piece of the whole chain that needs to come from an external source.

What a Subscription Actually Is

A subscription is a URL hosted by your provider. When the client accesses it, it gets back a full Clash config (or a node list), already containing the three major sections proxies, proxy-groups, and rules. The client re-fetches it at a set interval afterward, so when the provider swaps servers or adds/removes nodes, everything syncs locally on its own. Importing works the same way across every client: copy the subscription link, paste it on the subscription or config page, and confirm the download. For exactly where to click on each platform, the tutorial page has step-by-step instructions, so it won't be repeated here.

Understanding the Config File's Skeleton

What you download from a subscription is a YAML text file. You don't need to be able to write it, but understanding its skeleton helps a lot when troubleshooting. The global section of a minimal config looks like this:

mixed-port: 7890          # Local listening port shared by HTTP and SOCKS
allow-lan: false          # Whether devices on the local network can connect
mode: rule                # Proxy mode at startup
log-level: info           # Log level; bump to debug when troubleshooting
external-controller: 127.0.0.1:9090   # Local control API

Below that come proxies (node list), proxy-groups (proxy groups), and rules (rule list), in that order. The relationship between the three: rules point to proxy groups, and proxy groups point to nodes. If any name doesn't match up across sections, the config will fail to load, and the client's log will give you the exact line number.

What "Subscription Conversion" Means

If your provider only offers node info in another format (like a generic share link), it needs to go through a "subscription conversion" service that translates it into Clash config format. That conversion passes through a third-party server, which can see your subscription content—it's an extra exposure surface. Prefer a native Clash subscription whenever it's available; if conversion is unavoidable, use a trusted self-hosted or open-source converter.

When multiple devices share one subscription, "centrally managing the subscription link" is preferable to copying config files around between devices—see the multi-device sync notes for the trade-offs between three approaches.

Mode decides "whether the rule list even participates in the decision." The three modes are mutually exclusive global switches, toggled with one tap on the client's main screen, corresponding to the mode field in the config.

A common mistake is leaving GLOBAL on long-term. In global mode, traffic to local services also gets routed through an overseas node, which actually slows things down and burns through your traffic quota for nothing. The right approach: stay on RULE 99% of the time, and only use GLOBAL and DIRECT briefly as diagnostic tools—"works on GLOBAL, fails back on RULE" points to a rule problem; "fails on DIRECT too" means the issue isn't the proxy's fault at all.

System Proxy vs. Mode

Another switch that's easy to confuse is "system proxy." It isn't one of the three modes—it decides "whether the OS sends traffic into Clash at all": when enabled, the system-level proxy setting points to Clash's local port, and only apps that respect that setting (browsers, etc.) get routed through it; apps that ignore the system proxy (some games, command-line tools) bypass it entirely. To get every program routed into Clash without exception, you need TUN mode, covered in Chapter 7. Remember the layering with one line: system proxy/TUN decides whether traffic gets in at all; mode decides what happens to it once it's in.

Rule-based routing is what sets Clash apart from a simple proxy tool, and it's the entire logic behind RULE mode. The rule set bundled with your subscription covers most needs, but sooner or later you'll hit a moment where "this one site is being routed wrong"—that's when you need to be able to read rules, and sometimes add one yourself.

Rule Syntax

Each rule is a comma-separated line: type,match value,exit. The exit can be a proxy group name, or one of the built-ins DIRECT (direct connection) and REJECT (block). Common types:

Order Decides Everything

Rules are matched top to bottom, and the first one that matches takes effect immediately—everything below it is ignored. That's why the ordering follows a fixed logic: specific rules first, broad rules after, and a catch-all at the very end. Here's a minimal usable rule set for routing local vs. overseas traffic:

rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - DOMAIN-SUFFIX,openai.com,PROXY
  - DOMAIN-KEYWORD,google,PROXY
  - DOMAIN-SUFFIX,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

Reading it: known overseas domains go through the proxy; .cn suffixes go direct; IPs resolving to mainland China go direct; anything that matches none of the above falls through to the proxy. Note that GEOIP requires a DNS resolution to happen first to get an IP, so putting domain rules before it lets most connections get routed before resolution even happens; adding no-resolve to an IP-CIDR rule avoids triggering an unnecessary lookup for a purely domain-based connection.

Proxy Groups: Where Rules Exit To

PROXY in the example above is a proxy group name. Common group types: select for manual picking, url-test for periodic speed tests that auto-pick the fastest, and fallback for auto-switching to a backup node when the primary fails. A typical combo:

proxy-groups:
  - name: PROXY
    type: select
    proxies: [AUTO, HK Node, JP Node]
  - name: AUTO
    type: url-test
    url: http://www.gstatic.com/generate_204
    interval: 300
    proxies: [HK Node, JP Node]

An auto speed-test group nested inside a manual group: pick AUTO most of the time for a hassle-free setup, and manually lock onto a specific node when you have a special need.

Troubleshooting Path for Rules That Don't Work

1. Confirm you're actually in RULE mode—rules don't participate at all under GLOBAL or DIRECT.
2. Open the client's connections panel, find the target connection, and see exactly which rule it actually hit. Most "wrong routing" cases turn out to be intercepted by a broader rule higher up the list.
3. Check whether your custom rule was written after the subscription's rules—anything appended after MATCH will never get its turn.
4. If domain rules don't work but IP rules do, that's usually DNS-layer interference—cross-check with the fake-ip discussion in Chapter 7.

For a full walkthrough with real examples, see the blog's rule routing case study.

Chapter 5 left one gap open: the system proxy only affects apps that "respect the system proxy setting." Command-line tools, some game clients, and certain chat apps build their own connections and bypass the proxy entirely. TUN mode is the fix for that gap.

How It Works

With TUN enabled, the client creates a virtual network adapter on the system and sets it as the default route. Every app's network traffic—regardless of whether it respects proxy settings—first passes through this adapter into the Clash kernel, then gets routed by the rules. The effect is equivalent to a mobile VPN takeover: apps have no awareness of it, and routing applies system-wide. The cost is higher system privileges: on Windows it needs to run as a service or with admin rights, on macOS it needs a system extension authorization, and on Linux it needs the corresponding network management permissions. Every client walks you through authorization the first time you enable it, and it's a one-time approval.

Config Example

tun:
  enable: true
  stack: system
  auto-route: true              # Auto-configure the routing table
  auto-detect-interface: true   # Auto-detect the physical outbound interface

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

In graphical clients these are usually ready-made toggles, so you rarely need to write this by hand; it's shown here so you know what those toggles actually change underneath. stack is the protocol stack implementation—compatibility varies slightly between them, so try switching if a specific app misbehaves.

Why TUN Always Shows Up with fake-ip

Once TUN takes over traffic, DNS resolution also has to be handled by Clash consistently, otherwise you get a mismatch where "resolution happens outside, traffic happens inside," breaking domain rules. In fake-ip mode, the kernel returns a virtual IP from a reserved range for every domain lookup; the app connects using that virtual IP, and the kernel looks up the mapping table to recover the original domain for rule matching—this skips the wait for a real resolution while keeping domain rules fully reliable. The side effect is that a handful of IP-sensitive programs (local network discovery, certain login checks) may not handle this well; just add the relevant domains to the fake-ip filter list in that case.

Getting the config working is just the start. A proxy setup is infrastructure you'll use for a long time, and it's worth ten minutes to build a low-effort maintenance habit so you don't scramble when everything suddenly breaks one day.

Subscription Update Strategy

Set an auto-update interval for your subscription in the client—every 24 hours is a reasonable default; when your provider announces a server change, trigger a manual update right away. A failed update won't wipe out your existing nodes—the client keeps using the last cached copy—so an occasional failed update isn't worth worrying about; only check whether the subscription URL has been reset by the provider if it fails several days in a row.

Logs: Your First Stop for Troubleshooting

Every client has a log panel. Keep it at info level day to day; bump it to debug temporarily when troubleshooting, and you'll see the rule each connection hit, DNS resolution, and exit selection. Basic approach to reading logs: reproduce the issue, then check the most recent lines immediately—keywords to look for are usually error, timeout, and refused. Remember to switch back to info afterward; debug logs pile up fast and waste disk space if left on for long.

Backups and Multi-Device Consistency

There's very little you actually need to back up: the subscription link itself, any custom rule snippets, and settings you've changed in the client. Store the subscription link in a password manager, and keep custom rules as a separate text file. For multiple devices, prefer having each device pull the same subscription independently rather than manually copying config files around; some clients support WebDAV backup, which can sync your interface settings too. See the multi-device sync notes for a full comparison of three approaches.

Upgrading the Client

Client updates usually ship with kernel updates too, and it's worth staying current since new rule types and protocol support depend on kernel version. Before upgrading, check the release notes for any config incompatibility warnings; mainstream clients preserve subscriptions and settings across upgrades, but before a major version jump, copying out your subscription link first costs almost nothing and buys total peace of mind. New installers are always available on the download page for the corresponding platform.

Once you've worked through the first eight chapters, day-to-day use holds no more obstacles. This chapter lays out three directions for going deeper, ordered by return on effort.

Direction One: Take Ownership of Your Rules

The rules bundled with a subscription are your provider's generic solution—the first step toward advanced use is building your own rule layer. Most modern clients support a "config override" or "merge/script" mechanism: it injects your custom rules at the top of the rule list without touching the subscription's original file, so a subscription update never wipes out your changes. Start small: fix routing mistakes one by one as you encounter them, and after three months you'll have a rule layer that fits your exact usage patterns. Rule providers (rule-providers) are a more engineered way to organize things, splitting rules by purpose into independently updatable remote files—worth adopting once your rule count passes a hundred or so.

Direction Two: Understand mihomo's Extended Capabilities

The mihomo kernel extends the classic Clash config format with a fair number of extra capabilities: broader protocol support, finer-grained DNS control, process-level match rules, outbound interface binding, and more. Most of these require hand-written config snippets to enable, and the official documentation is the only authoritative source. The way to learn is to experiment one piece at a time: add one section, confirm it loads, then add the next—if there's a config error, the log will point to the exact line. Deploying the kernel plus systemd directly on a server or router is the capstone project for this direction—with no GUI to fall back on, every behavior is decided by the YAML you wrote.

Direction Three: Understand the Ecosystem, Judge Information Critically

The Clash ecosystem has a lot of projects and frequent renames, and plenty of tutorials you'll find online are based on already-archived old projects—following them blindly leads to trouble. Building a mental map of the lineage—which kernel is actively maintained, which clients are built on it, which projects have stopped—lets you quickly judge how current a tutorial actually is. The open-source lineage breakdown is a good entry point; after that, follow each project's own release page rather than secondhand reposts.

Recommended Learning Order

1. Get the basic flow working with the tutorial page, and use it steadily for two weeks.
2. Go back to Chapter 6, learn to read the rule list bundled with your subscription, and fix one real routing mistake you've actually hit.
3. Turn on TUN, understand fake-ip, and cover command-line tools and other system-wide scenarios.
4. Introduce config overrides and build your own rule layer.
5. Deploy a bare kernel on a spare device, completing the shift from user to administrator.

Each step builds on the muscle memory from the one before it—skipping ahead isn't recommended. Look up specific terms in the glossary, check client-related questions against the comparison page, and get the tool itself anytime from the download page.