The Complete Clash Manual: Zero to Pro

01Core Concepts: Core, Client, and Config File

The Core and the Client Are Two Different Layers

The Clash ecosystem has two layers. The bottom layer is the core: a command-line program that listens on a local port, receives application traffic, matches it against rules, and forwards it to the right proxy server or direct exit. The dominant core today is mihomo (the Clash Meta branch), which kept evolving after the original Clash core was archived, extending outbound protocols, rule sets, and the TUN stack — see the blog post "How mihomo Differs from the Original Clash Core".

The top layer is the graphical client: Clash Plus, Clash Verge Rev, FlClash, and other differently named apps are all essentially a "cockpit" for the core — importing subscriptions, switching nodes, toggling the system proxy and TUN, and showing logs and connections. Once you see it this way, a lot of confusion clears up on its own: the feature differences between clients are mostly about UI and packaging, while routing capability depends on the core; switching clients doesn't require switching subscriptions, since config files work across any core-compatible client.

The Three Building Blocks of a Config File

Everything the core does is governed by a single YAML config file (usually called config.yaml, referred to as a Profile in clients). No matter how long the file is, the skeleton always has three parts:

1. Inbound and global settings: listening port, LAN access toggle, run mode, log level, DNS settings.
2. proxies and proxy-groups: the node list (each node is one proxy server's address, port, protocol, and credentials) and proxy groups (nodes organized by strategy, referenced by rules).
3. rules: the routing rule list, deciding which proxy group each connection goes through.

A minimal, readable global settings block looks like this:

mixed-port: 7890        # combined HTTP/SOCKS5 inbound port
allow-lan: false        # whether LAN devices can connect
mode: rule              # run mode: rule / global / direct
log-level: info         # silent / error / warning / info / debug
external-controller: 127.0.0.1:9090   # local API control port

Quick Glossary of Frequent Terms

02Choosing a Client: Platform Matrix and Trade-offs

Platform First, Preference Second

The first constraint on choosing a client is the operating system. The table below matches what's listed in the Download Center, with each cell ordered by recommendation:

Clash Plus is the top pick across every platform: the interface and workflow are consistent on all five platforms, so switching devices doesn't mean relearning anything; it ships with the mihomo core and supports subscription import, TUN, and rule routing out of the box. Clash Verge Rev offers finer-grained configuration on desktop — override scripts, external control, and core switching all have dedicated entry points — suited to users willing to read documentation. FlClash is built with Flutter, giving one interface across desktop and Android; pick it if you prefer a minimal setup. Clash Nyanpasu is another Verge-family fork for Windows, with a different look but similar functionality. Clash Meta for Android stays closest to the core's native behavior on Android; Surfboard is compatible with the Clash config format and serves as an Android alternative.

03Installation: Walking Through Five Platforms

Windows

Get the installer from the Download Center's Windows section, double-click to run it, and pick an install folder in the wizard. Two common snags: first, SmartScreen may show "Windows protected your PC" — the default block for newly released installers — click "More info → Run anyway" to continue; second, after install you might not see a window at all, since Clash-family clients minimize to the system tray by default, so click the cat icon in the tray to bring up the main window. If you plan to use TUN mode, approve the service installation or administrator prompt the client asks for on first launch — it's used in Chapter 7.

macOS

Download the .dmg image, open it, and drag the app icon into the Applications folder. Mind the chip version: Apple Silicon (M-series) and Intel use separate installers, clearly labeled on the download page. If macOS shows "cannot verify developer" on first open, go to System Settings → Privacy & Security, scroll to the bottom, and click "Open Anyway," or right-click the app icon and choose "Open" then confirm again. When the client requests a helper service (used to take over the system proxy and TUN), enter your password to allow it.

Linux

For desktop distributions, the .deb package is recommended; install it directly on Debian/Ubuntu-family systems:

# filename depends on what you actually downloaded
sudo apt install ./clash-verge-rev_amd64.deb
# or use dpkg, then resolve dependencies
sudo dpkg -i ./clash-verge-rev_amd64.deb
sudo apt -f install

After installing, launch it from the application menu. TUN mode needs the core to have the CAP_NET_ADMIN capability or to run as a service — client settings usually include a one-click "service mode" toggle. Headless server environments skip the GUI entirely and run the mihomo core directly; see Chapter 9.

Android

Get the APK from the Download Center's Android section, and allow "install from this source" when prompted. The first time you tap connect, the system shows a VPN connection request dialog — the standard authorization for the VpnService mechanism; confirming it puts a key icon in the status bar, meaning traffic is now flowing through the client. Android skins with aggressive background management should also have the client added to the battery-saver allowlist and autostart list, or the proxy may get killed after the screen has been locked for a while — details in the blog post "Key Points for Using the Clash Android Client".

iOS

On iOS, get Clash Plus from the App Store — the download page's iOS section has a direct store link and the official site clashplus.io. On first launch, it likewise asks to add a VPN configuration; you can find the matching profile under Settings → General → VPN & Device Management. Subscription import and node switching work the same way as on desktop, so every concept in later chapters applies here too.

04Subscription Import and Config Management

What a Subscription Link Is

A subscription is an HTTPS URL generated by the service provider, whose content is a complete config file that updates in real time as nodes change. "Importing a subscription" in a client means: request that URL → save the returned YAML as a Profile → set it as the active config. That makes a subscription link equivalent to an account credential — never paste it somewhere public, and never leave it exposed in a screenshot.

Importing and Updating

1. Copy the subscription link from the provider's account dashboard, making sure to pick the Clash or mihomo format (some panels output different content per core).
2. Open the client's Profile/config page, paste the link, and click import. Success looks like a new entry appearing with usage and expiry info (if the panel provides it).
3. Select that entry to make it active. From then on, the node list, proxy groups, and rules all come from this config.
4. Set an auto-update interval (24 hours is common). If the provider changes node addresses and the local copy isn't updated, you'll see everything time out.

Local Configs and Managing Multiple Profiles

Besides subscriptions, clients also let you create a blank Profile or import a local YAML file — handy for self-hosted server users and anyone who wants full control over rules. Multiple Profiles are mutually exclusive: only one is active at a time, and switching replaces the port, node, and rule blocks all at once. A common approach is "one subscription plus one local experiment": use the subscription day to day, switch to the local copy when tinkering with rules, and switch back anytime it breaks. Every subscription update overwrites the remote content, so edits made directly on a subscription Profile get wiped out — persistent customization needs the override mechanism from Chapter 9. For a deeper look at Profile structure, see the blog post "What Is a Clash Config File".

05Proxy Modes and the System Proxy

Three Run Modes

The mode field in the config has three possible values. rule: each connection is matched against the rules list one by one, and goes wherever it matches — this is the recommended everyday mode, keeping traffic inside mainland China on direct connections and traffic outside on the proxy without them interfering with each other. global: skips the rules and sends all traffic into the same proxy group, useful only for temporarily checking whether a rule failed to match. direct: no traffic goes through the proxy at all, essentially keeping the client running while stepping aside. The switch sits on the client's main screen, usually as three options side by side.

What the System Proxy Does

Turning on the "system proxy" switch makes the client register an HTTP/SOCKS proxy address with the OS, defaulting to 127.0.0.1:7890 (the same mixed-port mentioned earlier). Browsers and most apps that honor system proxy settings will actively route traffic to this port. Its limitation lives in that word "actively": command-line tools, some games, and legacy apps don't read the system proxy setting, so their traffic never touches the core — that's what TUN mode in Chapter 7 is for.

Verifying the Connection Works

After connecting, confirm it two ways. First, check the client's connections panel: visit any website, and a new entry should appear showing the matched rule and exit node, proving the traffic is really flowing through. Second, test it from the command line with an explicit proxy flag:

# request through the local mixed port; getting response headers means the link works
curl -x http://127.0.0.1:7890 -I https://www.cloudflare.com

If direct connections work fine but going through the proxy times out, check in order: whether the node is usable (try switching nodes), whether the subscription has expired, and whether a local firewall is blocking the client.

06Rule Routing: Sending Every Connection Down the Right Path

How Rules Match

The rules list is matched top to bottom, stopping at the first hit. Each rule has the form "type, match value, target policy," where the target policy can be a proxy group or one of the built-ins, DIRECT or REJECT. The list must end with a catch-all MATCH rule to absorb anything not matched above. Commonly used rule types:

Order sensitivity is the most common beginner mistake: put GEOIP,CN,DIRECT ahead of a rule for a site outside China, and if that domain happens to resolve to a CDN node inside China, the connection will hit the direct rule too early. The principle is precise rules first, broad rules later, and MATCH always last.

The Four Proxy Group Strategies

A rule's target is usually a proxy group, not a single node, and the group's internal strategy decides the actual exit: select is manual — whatever you click in the UI is what's used; url-test periodically checks latency against a test URL and automatically picks the fastest node; fallback takes the first available node in list order, moving on automatically if the one ahead of it drops; load-balance spreads connections across multiple nodes. Here's a combination you can drop in directly:

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

rules:
  - DOMAIN-SUFFIX,openai.com,PROXY
  - RULE-SET,streaming,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

Day to day, leave the PROXY group on AUTO for automatic latency testing, and switch manually to a specific node when you need a fixed region (streaming unlock, for instance). For a deeper breakdown of the four dimensions of node selection — latency, multiplier, region, and protocol — see the blog post "How to Choose a Clash Node".

DNS and Fake-IP

Correct routing depends on domain information not getting lost. The dns section in mihomo supports two modes: redir-host resolves for real and matches by IP, while fake-ip fabricates responses from a reserved address range and restores the real domain when a connection is established — the latter noticeably cuts resolution latency and avoids DNS pollution interfering with routing. Apps that depend on real IPs (LAN discovery, certain game platforms) need to be listed in fake-ip-filter as exceptions; see the full mechanism in the blog post "How Fake-IP Mode Works, Explained".

07TUN Mode: Taking Over All System Traffic

How It Works and When to Use It

TUN mode has the core create a virtual network adapter and points the system's default route at it — every app's traffic gets intercepted at the network layer, no longer depending on whether the app respects system proxy settings. Command-line tools, game clients, and UWP apps — traffic that "ignores the system proxy" — all flow into the rule engine under TUN. The differences between the two approaches:

Steps to Enable It

1. Meet the permission requirement first: on Windows, install service mode in the client settings (or run as administrator); on macOS, approve the helper service authorization; on Linux, enable the client's service mode or grant the core network admin capability.
2. Turn on the TUN switch in client settings. For Verge-family clients, also turn off the system proxy switch to avoid double interception.
3. Confirm DNS hijacking is enabled, or apps that talk to the system DNS directly will bypass routing.

The corresponding config block (the client's GUI toggle is really just writing these fields):

tun:
  enable: true
  stack: system        # system / gvisor / mixed
  auto-route: true     # automatically take over the default route
  auto-detect-interface: true
  dns-hijack:
    - any:53           # hijack all DNS queries sent to port 53

08Maintenance and Troubleshooting

Three Things to Keep Updated

Subscriptions: turn on auto-update with an interval of 24 hours or less; if a provider announces a node change, manually update once to apply it right away. Client and core: an actively maintained client updates its core with each release, and new protocols and fixes depend on it — check the changelog for config field changes before upgrading. GEO data and rule sets: the GeoIP/GeoSite databases and the external files behind RULE-SET both have their own update mechanisms; client settings usually offer an "update GEO data" button, and it's worth updating before digging further when rule matching doesn't behave as expected.

Two Everyday Observation Windows

Logs: temporarily set log-level to debug to watch the matching process for every connection — the most direct way to find out exactly which rule a piece of traffic hit; switch it back to info once you're done, so logs don't flood and waste resources. Connections panel: lists active connections' destinations, matched rules, exit nodes, and traffic in real time — when an app is exiting through the wrong node, grab its destination domain here and add a precise rule back in the config.

Troubleshooting Table

09Advanced Path: From Capable to Proficient

Overrides: Making Customizations Survive Subscription Updates

Every subscription update overwrites the whole Profile, so customizations made by editing the file directly won't survive the next refresh. The right approach is an override (Merge/Override): keep a separate patch in the client that gets layered onto the config automatically after every subscription update. Typical uses are appending your own rules, pinning a DNS block, or forcing the TUN field on. Clash Verge Rev also supports JavaScript-based overrides that can rewrite nodes and proxy groups conditionally in bulk, useful for anyone managing a lot of rules.

External Control API and Web Dashboard

The core exposes a RESTful API through external-controller, and the client's own interface is just one consumer of it. You can call it directly too:

# view the current config
curl http://127.0.0.1:9090/configs
# switch the exit node of a select group
curl -X PUT http://127.0.0.1:9090/proxies/PROXY \
  -d '{"name": "HK-01"}'

Pairing it with the external-ui field lets you mount a web dashboard, managing the running core from a browser — the standard way to operate it on routers and servers.

Running the Core Without a GUI

Servers, software routers, and NAS boxes don't need a GUI — grab the mihomo binary for the matching architecture (AMD64/ARM64/ARMv7/MIPS, and so on) from the Download Center's core section, place the config in the target directory, and start it:

# -d sets the config directory, which holds config.yaml and the GEO data
./mihomo -d /etc/mihomo
# run persistently with systemd and start on boot
sudo systemctl enable --now mihomo

Point other LAN devices' gateway or proxy at this machine, and the whole household shares the same routing rules.

A Recommended Reading Order for Going Further

1. Profile Structure Basics and Managing Multiple Configs — fully internalize the config skeleton from Chapter 4.
2. The Four Dimensions of Node Selection — build your own node-picking process.
3. How Fake-IP Works — understand what's happening at the DNS layer.
4. How mihomo Differs from the Original Core — know the limits of the tool you're using.
5. Hands-on practice: maintain your own rule patch with an override, then deploy the bare core on a spare device. Work through these five steps, and the nine chapters in this manual truly become your own knowledge.