Zero to Mastery
The Complete Clash Handbook

Core Concepts: Sort Out Four Terms First

Nine times out of ten, people who get stuck starting out with Clash aren't stuck on the steps — they're stuck on terminology. Core, client, subscription, rule: each word covers a different piece. Sort out the division of labor first, and every chapter after this gets easier.

Core and Client: One Engine, Many Faces

The thing actually handling traffic is the core — the current mainstream implementation is mihomo (often called the Clash Meta core in the community). The core is a command-line program that reads a YAML config file, listens on a local port, and routes each connection to a proxy or a direct connection according to the rules. It has no interface; it doesn't care about looking good, only about forwarding traffic.

The apps you tap open on desktop or mobile — Clash Plus, Clash Verge Rev, FlClash — are all clients: they bundle or call the core, translate "edit a config file" into toggles and buttons, and translate "read the logs" into charts and lists. Switching clients doesn't mean switching cores, and config files are largely portable between different clients — which is why the principles covered in this handbook hold true across all of them.

Nodes, Subscriptions, Config Files: Three Layers of Containers

A node is the connection parameters for one proxy server: address, port, protocol, password. A subscription is a URL that returns a batch of nodes (usually already packaged into a full config) when you visit it; it's maintained by a provider, and you just refresh the subscription whenever nodes change. A config file (Profile) is the actual YAML the core reads — besides nodes, it also contains port settings, DNS, proxy groups, and rules. Whatever a subscription pulls down eventually becomes a Profile. The relationship across three layers: nodes go into a subscription, the subscription generates a config file, the config file feeds the core.

Proxy Groups and Rules: The Traffic Dispatch Desk

A proxy group organizes several nodes into a selectable queue — a "manual select" group lets you pick yourself, an "auto latency test" group switches automatically based on latency. A rule is a top-to-bottom matching list that decides which proxy group a given connection goes into, or whether it connects directly: local sites go direct, specific domains go through a proxy, everything else falls back to a catch-all rule. Whichever rule matches gets the traffic — this mechanism is expanded in CH-06.

There are more terms than these. DNS pollution, Fake-IP, GeoIP — look these up when you hit them, no need to memorize in advance. The site has a glossary organized by category — switch over to it anytime while reading this handbook.

Choosing a Client: Match It to Your Platform

Choosing a client only answers two questions: what OS are you on, and how much customization do you need. The universal top pick across platforms is Clash Plus — available for Windows, macOS, Android, and iOS, with a consistent interface. Importing subscriptions, switching modes, and enabling TUN are all one-click actions, good for beginners through advanced users alike. Below are the combinations this site's download page covers, listed by platform.

What to Look at When Choosing

Three dimensions are enough: maintenance status — prefer clients still actively updated; Clash for Windows and ClashX Meta are no longer maintained, and while the download page keeps an archive entry for them, new users shouldn't start there; core version — confirm the client uses the mihomo core to get full support for newer protocols and rule types; feature coverage — if you need TUN mode, confirm your platform's build offers it; for fine-grained rule editing, a Verge Rev-style tool is a better fit as your primary client.

A full parameter-by-parameter comparison, interface differences, and migration tips are all laid out on the site's side-by-side comparison page. Once you've decided, head to Get the Client and download by platform.

Installation: Key Points Across Five Platforms

Installing itself isn't hard — the difficulty is that each platform's security mechanisms block you at a different point. This chapter lists installation paths and how to get past each block, by platform. Once installed, launch it once to confirm the main window opens before moving to the next chapter on importing subscriptions.

Windows

Get the installer from the Windows section of the download page and double-click to run it. Avoid installing into a directory with non-ASCII characters or spaces, which reduces path issues later when the core reads the config. If SmartScreen pops up on first run, click "More info → Run anyway"; when the firewall asks about network permissions, check both private and public networks, otherwise LAN-related features won't work.

macOS

After downloading the dmg, drag the app into the Applications folder. Watch the architecture: pick the ARM build for Apple Silicon (M-series chips) and the x64 build for Intel machines — installing the wrong one will noticeably slow things down or fail to launch. If macOS says the developer can't be verified on first open, go to System Settings → Privacy & Security and click "Open Anyway" near the bottom of the page. The client will ask for an admin password once, the first time it takes over the system proxy or installs a helper service.

Android

When installing the APK, the system will ask you to allow "install unknown apps" — grant this permission once for your browser or file manager on the settings page that pops up. The first time you tap connect, the system shows a VPN connection request — this is Android's standard way of taking over traffic, and you must allow it or the proxy won't work. On heavily customized Android skins, do two more things: add the client to the battery optimization allowlist and permit background activity, so the proxy doesn't get killed after the screen locks.

iOS

The iOS build of Clash Plus is distributed via the App Store; go to the iOS section of the download page to reach the store listing and install. On first launch, follow the prompts to add a VPN configuration profile — the system will ask you to verify once with a password or Face ID. Once installed, importing a subscription works the same as on other platforms, covered in the next chapter.

Linux

For desktop distros, Clash Verge Rev's deb package is recommended: sudo apt install ./package-name.deb completes the install in one step with dependencies resolved automatically. Arch-based systems can get a community-maintained build from the AUR. For headless servers and routers, skip the GUI entirely and run the mihomo core directly — see CH-09.

Subscriptions and Config Files: Loading Nodes Into the Client

An installed client is just an empty car — the subscription is the passenger. This chapter covers the import process, the internal structure of a Profile, and how to manage several configs at once.

The Standard Steps to Import a Subscription

Copy the subscription URL from your provider. Open the client's "Config / Profiles" page, choose "Import from URL," paste the link, and confirm. The client downloads the subscription content, parses it into a Profile, and enables it automatically. Signs of a successful import: the proxy page shows a list of nodes, and the node names aren't blank. If the import fails, first check that the link is complete (many input fields drop trailing characters), then work through Subscription Update Failed: Troubleshooting category by category.

The Three-Part Profile Structure

The YAML a subscription pulls down usually has three major sections: proxies defines nodes, proxy-groups defines proxy groups, and rules defines routing rules. Here's the skeleton (parameter values are examples):

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies:
  - name: "HK-01"
    type: ss
    server: server.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - HK-01

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

Line by line: mixed-port is the local listening port that both HTTP and SOCKS requests come through; mode is the proxy mode at startup; the select group named PROXY under proxy-groups is the dropdown list you manually pick nodes from in the UI; rules match top to bottom, with the final MATCH line as the catch-all. Understand this skeleton, and you understand any config a subscription can generate.

Multiple Configs and Auto-Update

You can import several subscriptions at once, but only one Profile is active at a time — switching replaces the whole thing at once, nodes and rules together; there's no such thing as two configs' rules stacking. A management tip: give each config a recognizable name (provider + purpose) and delete retired ones promptly to avoid accidentally switching to a stale config. See Managing Multiple Profiles for naming conventions and rule-override pitfalls.

Auto-update is set on the config's edit page, usually under a field called "Update Interval." 12–24 hours is a reasonable range: too short wastes requests, too long means missing a provider's node rotation. The manual update button is usually the refresh icon on the config card — watch the timestamp change before and after to confirm you actually pulled new content.

Proxy Modes: Rule, Global, or Direct

The mode decides whether the rule list participates in the decision at all. Three modes, three behaviors:

Keep Rule mode for everyday use. Leaving it on Global mode will noticeably slow down access to local sites and burn through data for no reason — if you notice "everything is going through the proxy," the first thing to check is whether the mode got switched to Global.

System Proxy: The Prerequisite for a Mode to Take Effect

Picking a mode is only half the job — apps also need to hand their traffic over. Turning on the client's "System Proxy" switch registers 127.0.0.1:7890 (port depends on your config) with the OS as the proxy server, and apps that respect the system proxy setting — like browsers — will automatically send requests to that port. Note its limit: only apps that respect the system proxy get captured; many command-line tools and game clients ignore this setting entirely — which is exactly the problem CH-07's TUN mode solves.

Verifying the Proxy Actually Works

Don't go by feel — verify with a command. Run this in a terminal:

curl -x http://127.0.0.1:7890 -I https://www.google.com

Getting back a HTTP/2 200-type status line means the whole chain — "local port → node → target site" — works; if it hangs or errors out, the issue is with the node or config, not the browser. For a full troubleshooting order when the connection succeeds but pages won't load, see the nine-point checklist.

Rule-Based Routing: Send Each Connection Down the Right Path

Rule-based routing is Clash's core difference from "one-click global proxy" tools: at the same moment, local traffic goes direct, traffic to sites outside your region goes through the proxy, and ad domains get blocked outright — all without interfering with each other. Understanding it only takes two things: what a rule looks like, and the order it's matched in.

Common Rule Types

Matching Order: Top to Bottom, First Match Wins

The rule list is checked from the first entry down, and the first match wins and stops the search. So order is priority: put exact rules first, broad rules later, and MATCH always at the very bottom. A typical rules section:

rules:
  - DOMAIN,dl.example.com,DIRECT
  - DOMAIN-SUFFIX,github.com,PROXY
  - DOMAIN-KEYWORD,google,PROXY
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

Reading it: first, let a download domain that must go direct through directly; then send all of GitHub and anything with "google" in the domain through the proxy; LAN ranges go direct without DNS resolution (no-resolve keeps internal addresses from being sent out for resolution); IPs geolocated to mainland China go direct; everything else goes through the proxy. If a site is going down the wrong path, scan top to bottom for the first rule that matches it — that's your answer.

The Right Way to Add Custom Rules

Every subscription update overwrites the whole Profile, so editing rules directly inside the subscription file gets wiped out on the next update. The right approach is to use the persistence mechanism your client provides: Clash Verge Rev's "Global Merge / Override" and equivalent Override features in other clients let your custom rules get automatically merged in — placed first — every time the subscription updates. The principle stays the same: custom rules must come before subscription rules to take priority.

The GeoIP Database

GEOIP,CN,DIRECT works thanks to a local IP-geolocation database. If that database gets stale, newly assigned IPs in mainland China may get misjudged as being outside it, showing up as "local sites randomly going through the proxy for no reason." Client settings usually have an "Update GeoIP / Geo Data" button — click it every month or two; restart the core after updating for it to take effect.

TUN Mode: Capturing Traffic the System Proxy Can't Reach

CH-05 covered the system proxy's limit: it's a "gentleman's agreement" that only binds apps willing to follow it. Command-line tools, some desktop software, and game clients often bypass it and connect directly. TUN mode takes a different approach, solving the problem at the network layer.

How It Works: A Virtual Network Adapter

With TUN enabled, the core creates a virtual network adapter on the system and points the default route at it — after that, all outbound traffic, regardless of whether the app cooperates, passes through this adapter into the core first, then gets routed by the same rule set. The system proxy is "please come find me"; TUN is "every car must pass through this checkpoint." The trade-off is it needs elevated privileges (usually a service mode install on Windows, a system extension authorization on macOS) and a matching DNS setup.

DNS and Fake-IP

The core's DNS must be enabled in TUN mode, otherwise domain resolution bypasses the core and domain-based rules stop working. Fake-IP mode is recommended: the core immediately returns a placeholder IP from a reserved range so the connection can start right away, deferring the actual resolution until forwarding time — saving a round trip of waiting. Example config:

tun:
  enable: true
  stack: system
  auto-route: true
  auto-detect-interface: true

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

Enabling and Verifying TUN

Mainstream clients already turn the block above into a toggle, so you don't need to write it by hand. Windows: install "Service Mode" first in settings (needs admin rights), and once it shows as running, turn on the TUN switch; macOS: turn on the TUN switch, authorize the network extension when prompted, and enter your password once. To verify: turn off the system proxy switch, leave only TUN on, and run a command in the terminal that doesn't go through the system proxy (e.g. nslookup github.com) — if the result lands in the 198.18.x range, DNS hijacking is working and TUN is doing its job.

Routine Maintenance: Keeping the Proxy Stable Long-Term

Getting it configured is just the start. A proxy is infrastructure you run long-term — a few small, periodic actions avoid most "it worked fine yesterday" problems.

Node Latency Testing and Auto-Switching

The latency test button on the proxy page sends a probe request to every node; the number is the round-trip time in milliseconds for "local machine → node → test target." Rule of thumb: under 200ms is smooth for daily use, over 500ms or a timeout means it's time to switch. If you don't want to pick manually, point your commonly used apps at a url-test type auto-latency group, and the core will periodically pick the best one. Note that latency only reflects response speed, not bandwidth — whether video playback stutters also depends on the node's actual quality.

Reading Logs to Pinpoint Issues

The client's log (or connections) page is the first place to look when troubleshooting: each entry includes the target domain, the rule that matched, and the node used. When "a site won't load," search for the domain here first — matched DIRECT but needs the proxy, that's a rule problem; matched a proxy group but timed out, that's a node problem. Once you know the direction, fixing it goes fast.

Launch on Startup

On desktop, turn on "Launch at Startup" in settings, usually paired with "Silent Start" to leave just a tray icon. On Windows, if autostart fails, check whether the startup entry in Task Manager has been disabled by third-party optimization software; on Android, refer back to CH-03's background-permission settings. For more frequent questions, the FAQ page organizes them into four categories: basic concepts, installation & setup, usage tips, and troubleshooting.

Advanced Path: From Using It to Understanding It to Writing It Yourself

Get through the first eight chapters and everyday use has no more obstacles. If you want to go further, three directions to work through in order.

Direction One: Hand-Writing and Overriding Configs

Stop treating your subscription as a black box. Use CH-04's skeleton to read through your current active Profile section by section; then start with small changes — add your own rule via the override mechanism, change a proxy group from select to url-test, adjust the DNS nameserver list. After each change, reload the config and check the logs to confirm the behavior matches what you expect. Once you can write configs by hand, any client is the same tool in your hands.

Direction Two: Running the Core Directly

Servers, NAS boxes, and routers have no GUI — run the mihomo core directly. Grab the archive for your architecture from the core section of the download page, then extract it:

mkdir -p ~/.config/mihomo
mv config.yaml ~/.config/mihomo/
./mihomo -d ~/.config/mihomo

-d specifies the working directory, where the core reads config.yaml and the Geo data files. Once it runs in the foreground successfully, set up a systemd service for autostart and crash recovery. Point other devices on the LAN at this machine's IP and port; remember to set allow-lan: true in the config, and one machine can serve the whole household.

Direction Three: The External Controller API

Declaring external-controller: 127.0.0.1:9090 in the config exposes a RESTful API from the core — switching nodes, querying connections, and reloading config can all be done via HTTP requests:

curl http://127.0.0.1:9090/proxies

Various web dashboards (like metacubexd) are built on top of this API. Being able to use it means you can script automation like scheduled node switching or alerting on failures — at this point, you've gone from user to builder.

Wrapping Up the Roadmap

1. Get comfortable with one GUI client, using Rule mode without thinking about it (CH-01–05);
2. Learn to read rules and logs, and pinpoint "why this site is going down the wrong path" yourself (CH-06, 08);
3. Turn on TUN, and understand how network-layer capture works with DNS (CH-07);
4. Hand-write configs, run the core directly, and automate via the API (this chapter).

Each step builds on the one before it. Use the tool that matches whichever stop you're at; when it's time to act, go back to the Quick Start Guide for the steps, and pick your gear at Get the Client. The route map is here — you decide when to depart.