Clash from Beginner to Advanced: Complete Handbook for Setup, Subscriptions and Rule Routing

This handbook is organized in learning order, and each chapter builds on the one before it: you need to understand how the kernel and the client divide the work before you can tell which layer owns each setting, and you need a subscription imported before rules and TUN have anything to route. Read it straight through the first time, then keep it as a reference and jump to the relevant chapter from the table of contents above when a specific problem comes up. Every config snippet here can be copied into the matching section of config.yaml. The server addresses, passwords and subscription links in the examples are placeholders; in real use they come from your subscription or your own server.

Core concepts: how Clash, the kernel and the client relate

The word Clash refers to three different things depending on context: a configuration spec for rule-based proxying, the kernel program that implements that spec, and the GUI clients built on top of it. The place beginners get stuck most often is assuming that downloading a Clash means downloading one app — in practice, what you open every day is the GUI client, while the kernel is what actually establishes connections, resolves domains and forwards traffic according to rules. Once you understand this two-layer split, it becomes obvious where each setting lives and why some changes require restarting the kernel.

The kernel: the layer that actually handles traffic

The kernel is a command-line program with no interface. On startup it reads a YAML config file and then does four things: it listens on local ports for connections from apps, organizes the nodes in the config into usable outbounds, decides which outbound each connection takes by walking the rules section, and writes the decision process to the log.

mihomo (formerly Clash Meta) is the mainline kernel maintained by the community today; the original Clash kernel is no longer maintained, and nearly all newly released clients are built on mihomo. The kernel itself does not handle subscriptions: it never downloads configs and never updates itself — it only knows the file it read at startup. If the config file changes, you have to reload or restart the kernel for it to take effect.

GUI clients: config management and the interactive shell

The GUI client handles everything outside the kernel: downloading a subscription link into config.yaml, providing switches for modes and nodes, rendering kernel logs into a readable panel, staying resident in the system tray or notification area, and launching the kernel at boot. Different clients present the same config differently, but in the end they all hand the file to the kernel to execute.

There is a very practical corollary here: when you switch clients, the subscription link usually carries over, and only the client's own settings need re-adapting — port numbers, the TUN switch, where rule overrides live. Node definitions are not stored in the client, so changing the shell does not mean rebuilding your nodes.

The three-layer structure of a config file

A typical config.yaml has three sections: base settings (ports, mode, log level, DNS), outbound definitions (proxies and proxy-groups), and routing rules (rules). The order of the three can be rearranged in the file, but the logical relationship is fixed: first define which nodes and outbound groups exist, then decide which traffic goes out through which one.

mixed-port: 7890
mode: rule
log-level: info

proxies:
  - name: "node-a"
    type: ss
    server: 203.0.113.10
    port: 8443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "PROXY"
    type: select
    proxies: ["node-a", "DIRECT"]

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

The 203.0.113.10 in the example is a documentation-reserved address; in a real config, server and password come from your subscription and do not need to be written by hand. This snippet is already a minimal working skeleton: local port 7890 accepts connections, rule mode, one manual selection group, and three rules matched from top to bottom.

How this handbook and the quick start guide divide the work

Quick Start Guide is a three-step main line: import a subscription, choose a mode, verify connectivity — the goal is to get online fast. This page is the systematic reference: the same nine stages, but each one expands into principles, what the parameters mean, edge cases and troubleshooting branches. For a first install, follow the guide page through the main line, then come back to the matching chapter here whenever you wonder why a setting is the way it is.

Choosing a client: filter by platform and maintenance status

Three criteria

First, the kernel. Whether a client is built on mihomo or otherwise compatible with Clash config syntax determines which fields it can parse. Clients based on the original Clash kernel cannot keep up with new protocols and rule types; when they hit an unknown field in a subscription they either throw an error or silently ignore it, which shows up as a subscription that updates fine but ends up with half the nodes missing.

Second, maintenance status. How often a client is updated determines how quickly it adapts to new OS releases. An unmaintained client still runs, but when the OS updates or the kernel gains new features there will be no fixes, and you are on your own when something breaks.

Third, feature coverage. Three points differ the most: whether TUN mode is supported, whether multiple configs can be switched quickly, and whether rule override and merging are supported. Users who only proxy a browser will not care about the first one, while anyone who needs to proxy games or UWP apps must confirm it.

Desktop: Windows and macOS

On Windows, Clash Plus is the current top pick, with installers covering both x64 and ARM64. Clash Verge Rev and FlClash offer comparable config management with a different interface layout. Clash Nyanpasu has a simpler interface and suits users who only need the basics. Clash for Windows is no longer maintained and is kept only as an archive option for legacy environments or migrating old configs.

On macOS, Clash Plus is again the top pick, with Clash Verge Rev and FlClash as alternatives. ClashX Meta is no longer maintained; users migrating from it should watch for config differences — policy group naming and the DNS section are stricter in the new kernel, and shorthand fields in old configs may not be recognized.

Mobile: Android and iOS

In the Android ecosystem, Clash Plus, Clash Meta for Android and FlClash all support TUN and per-app proxying — per-app proxying decides which apps go through the proxy and which connect directly, and it matters more on phones than on desktop. Surfboard uses a different config format, so before importing a subscription, check whether your provider offers output in that format.

On iOS, clients are limited by the system and can only be installed from the App Store. Clash Plus is available on the App Store, with its official site at clashplus.io; config import works like other iOS proxy tools, through a system VPN configuration profile.

Linux and server scenarios

On Linux desktop distributions you can use Clash Verge Rev or FlClash, with both deb and rpm packages available. Servers and routers have no graphical interface, so you use the mihomo kernel directly: download the archive for your architecture, extract it and start it from the command line, then keep it running with a systemd unit or a process supervisor script. The upside of this route is the lowest resource usage; the price is that every setting has to be written by hand.

A full side-by-side comparison and selection advice are in the client selection guide; every installer is grouped by platform on the download page, where platform links jump straight to the matching section. There is no need to agonize over the choice: the same subscription works across most clients, so install one and start using it, then adjust based on what you actually find missing.

Installation: system requirements, permissions and first launch

Three things to confirm before installing

System version. Windows 10 1809 or later; below that you are limited to system proxy mode, since the virtual network adapter driver and some system interfaces are unavailable. macOS needs a reasonably recent version to support the network extension mechanism — on older systems TUN cannot be authorized. On Android you need to allow installing apps from a browser or file manager, and some ROMs ask for a second confirmation during install. Linux distributions need to meet the client's glibc requirements; on very old releases, go straight to the kernel command-line route.

Permissions. TUN mode needs administrator rights (Windows) or root, plus network extension authorization (macOS, Linux). System proxy mode alone works with normal permissions. During installation you can leave TUN off and turn it on after the config is imported, so you are not changing two variables at once.

Network environment. The first launch may need to download rule sets or the GEOIP database; if the network is unreachable, the client will sit at the initialization stage. If your network is restricted, first check whether the client's own initialization requests are being blocked, then decide whether to switch to an offline config.

Windows installation order

• From the Windows section of the download page, pick the installer for your architecture: x64 for ordinary PCs, ARM64 for ARM devices. Installing the wrong architecture gives an immediate incompatibility warning.
• Run the installer and keep the default install directory.
• If an administrator permission prompt appears on first launch, allow it — this prepares the virtual network adapter driver for TUN mode.
• After launch, confirm the tray icon appears; its right-click menu should show mode switching, config management and exit.
• If it will not start after installation: first check whether the system blocked an unsigned driver install, then whether antivirus quarantined the main program, and finally whether a leftover service process from an older version is holding the port.

macOS and Linux

On macOS, download the dmg and drag it into the Applications folder. If Gatekeeper blocks the first launch, go to System Settings → Privacy & Security and choose to open it anyway. When you enable TUN, the system will ask you to authorize a network extension — you must allow this, otherwise TUN cannot take over traffic; if it still does not work after authorizing, restart the client once so the extension reloads.

On Linux desktop distributions, prefer the deb or rpm package and launch from the application menu after installing. Some clients use a split interface-plus-service architecture: the kernel runs as a service and the interface controls it over a local API, so the interface does not need root. Just install the service component as the installer prompts. For servers, skip the GUI: download the mihomo kernel archive, extract it, and start it with -d to set the config directory and -f to set the config file.

Mobile installation

On Android, the first launch after installing the APK asks for VPN permission; this permission is the basis of TUN mode, and if you deny it you can only configure a system proxy manually, which is a poor experience on mobile. On iOS, after installing from the App Store, the first connection walks you through adding a VPN configuration profile; allow it in system settings as prompted, then return to the client to import your subscription.

The common first-install pitfalls (permissions, ports and system proxy) are collected in the blog post Clash First Install and Initial Setup; run through it as a checklist once installation is done.

Subscription import: links, hosted configs and local files

What a subscription link really is

A subscription is just a URL: the client requests it and gets back a YAML config or an encoded node list. Clash-family clients need the Clash format (YAML); if your provider gives you a generic format, convert it first or pick a subscription output that supports that format. The link usually carries a query parameter as an identity token, so the link itself is a credential — do not share it publicly and do not expose the full parameters in screenshots.

The order of operations for importing

• Copy the full subscription link, including every parameter after the question mark.
• Open the client's profiles or subscription page and create a new profile. Different clients call this entry Profiles, Subscriptions, Configs or Nodes, and it is usually the first item in the sidebar.
• Paste the link and give it a name — the name only affects local display, not the connection.
• Click download or update and wait for the config to be fetched. This pulls both the node list and the rules, and on a poor connection you may need to try again.
• Select this profile so the kernel loads it.
• Go back to the proxies page, confirm the node list has appeared, and pick any node.

Hosted configs versus local edits

A remote subscription overwrites the local file in full on every update, so editing the config.yaml downloaded from a subscription directly means your changes are lost on the next update. This is the most common frustration for beginners: half an hour of rule writing gone overnight. Three ways to handle it:

• Use the client's built-in override or merge feature. Put your custom rules in a separate override file that is merged in on each subscription update, leaving the original subscription untouched.
• Local config. Save the subscription contents as a local file and maintain it by hand. The upside is full control; the price is that the node list no longer updates automatically.
• Self-hosted config. Maintain a complete config yourself and pull the nodes from the subscription through proxy-providers, writing all rules and policy groups on your own.

proxy-providers:
  provider-a:
    type: http
    url: "https://example.com/subscribe?token=xxxx"
    interval: 86400
    path: ./providers/provider-a.yaml
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

interval is in seconds, so 86400 means one update per day; health-check sets the target address and frequency for node latency tests. Once nodes come from a provider, reference them in proxy-groups with use: ["provider-a"] instead of listing node names one by one — when the subscription updates and nodes change, the policy group needs no edits.

What to do when an update fails

Start with the response code for the subscription request in the client log: 401 or 403 usually means the link expired, the parameters were changed, or the provider blocked your current IP; a request timeout means the path from your machine to the subscription server is broken; a parse failure means what came back was not Clash format, possibly because the provider returns different formats per client type. If only some nodes change after an update, that is normal — providers adjust nodes all the time and nothing needs fixing.

For keeping configs consistent across devices, see the blog post Clash Multi-Device Config Sync, which compares the use cases and maintenance cost of three approaches.

Proxy modes: rule, global, direct and system proxy

How the three modes divide the work

Rule mode (rule) matches the rules section line by line and takes whichever rule hits first; this is the default for everyday use. Global mode (global) sends all traffic through the currently selected node and ignores the rules — its value is diagnosis: if you suspect a bad rule, switch to global and, if the connection works, the problem is in your rules. Direct mode (direct) sends nothing through the proxy and is used to rule out the client itself: if even direct fails, the problem is not in the proxy chain.

The three modes are set by the mode field in the config file, and can also be switched temporarily in the client interface; after a restart, the config file wins.

System proxy versus TUN

System proxy means the client changes the operating system's proxy settings (Internet Options on Windows, Network preferences on macOS), and it only affects programs that respect those settings. Browsers and most command-line tools do; some games, UWP apps and software with its own network stack do not, and their traffic goes out directly.

TUN mode creates a virtual network adapter and points the system's default route at it, so all IP-layer traffic is taken over by the kernel regardless of whether an app respects the system proxy. The price is that it needs administrator rights and can conflict with some VPNs and virtual machine networks over routing.

The other difference is DNS: under system proxy mode, an app's DNS queries are handled by the system; under TUN mode, DNS is also taken over by the kernel, which is what makes domain-based rule matching with Fake-IP possible — chapter 7 covers this in detail.

Ports and the control interface

mixed-port serves both HTTP and SOCKS5 on one port and is the recommended single entry point today; older configs may split it into port (HTTP) and socks-port (SOCKS5). external-controller is the control interface that dashboards use to read the connection list and logs. By default it only listens on 127.0.0.1, so only the local machine can reach it; if you need other devices on the LAN to reach the dashboard, change the listen address to 0.0.0.0 and set a secret, otherwise you are exposing the control interface to the whole network.

mixed-port: 7890
allow-lan: false
external-controller: 127.0.0.1:9090
secret: "your-password"
mode: rule
log-level: info

allow-lan controls whether LAN devices can go online through this machine's proxy, which is a different thing from external-controller: the former opens the proxy port, the latter opens the control interface.

Suggested order

Start with system proxy plus rule mode and confirm the nodes work and the browser can reach sites; only turn on TUN when you hit a program that does not work. Do not enable TUN right away: when something breaks you then have to judge four factors at once — nodes, DNS, the virtual adapter and the routing table — which is far more expensive to debug. The seven troubleshooting steps for unreachable nodes are in the blog post Clash Node Timeout and Connection Failures.

Rule routing: rules syntax, policy groups and priority

Matching: top to bottom, first hit wins

The kernel compares from the first entry in the rules array downward, and the first rule that matches decides where the connection goes; later rules are not consulted. So array order is priority: put the narrowest, most specific rules first and the broad fallback last. MATCH must be the final entry — placing it earlier disables every rule after it, the most damaging mistake you can make in a rule list.

Common rule types

• DOMAIN: matches a domain exactly, hitting only the one you wrote.
• DOMAIN-SUFFIX: matches a domain suffix, so example.com also matches a.example.com and b.example.com.
• DOMAIN-KEYWORD: matches any domain containing the keyword; the scope is broad and false positives are easy, so use it sparingly.
• IP-CIDR: matches a destination IP range. Pure IP rules need a DNS result before they can be evaluated; adding no-resolve avoids an extra lookup just to match a rule.
• GEOIP: matches by IP geolocation, often used to send mainland China addresses direct, and usually placed after domain rules.
• PROCESS-NAME: matches by the name of the program that opened the connection; available on desktop, generally unsupported on mobile.
• RULE-SET: references an external rule set file, keeping hundreds or thousands of rules in a separate file.
• MATCH: the fallback rule that catches all remaining connections and must be last.

Policy groups: the outbounds rules point to

proxy-groups defines the outbound groups that rules can point to, and a group can contain nodes or other groups. Four common types: select for manual choice, where you use whichever one you click in the interface; url-test, which periodically tests the nodes in the group and automatically picks the lowest latency; fallback, which takes the first available node in order; and load-balance, which spreads connections across several nodes.

Groups can be nested. A common three-layer structure is manual selection group → automatic latency group → individual nodes: use the automatic group day to day and switch in the manual group when you need to pin something.

proxy-groups:
  - name: "PROXY"
    type: select
    proxies: ["AUTO", "DIRECT"]
  - name: "AUTO"
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies: ["node-a", "node-b"]

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - DOMAIN-KEYWORD,analytics,DIRECT
  - IP-CIDR,203.0.113.0/24,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

tolerance is the switch threshold in milliseconds: a new node must be faster than the current one by more than this before the group switches, which prevents flapping between two nodes with similar latency. interval is the test interval in seconds; set it too short and low-powered devices will run latency tests continuously.

Common mistakes

• Putting MATCH in the middle: every rule after it becomes dead code.
• Placing GEOIP before specific domain rules: domains that should be proxied get judged as domestic addresses and sent direct.
• Using IP-CIDR without no-resolve: every connection triggers a DNS lookup first and latency rises.
• Pointing a rule at a policy group name that does not exist: the kernel errors out or rejects the connection, with a clear message in the log.
• Mixing case in type names: domain-suffix is not recognized; type names must be uppercase.
• A wrong path to a rule set file: it is silently skipped at startup, which shows up as every domain that rule set covered falling through to the fallback.

A line-by-line breakdown with more examples is in the blog post Clash Custom Rule Syntax and Priority.

TUN mode: virtual adapter, DNS and Fake-IP

What TUN does

Once enabled, the kernel creates a virtual network adapter (Wintun on Windows, utun or tun on macOS and Linux) and points the system default route at it. Packets from applications reach the virtual adapter first, the kernel reads them and processes them by rule, then decides whether to connect directly or go through the proxy. Because it works at the IP layer, it does not depend on whether an app respects the system proxy, so games, UWP apps and software with its own network stack are all covered.

The cost comes from the same layer: the routing table is rewritten, which can conflict with VPNs, virtual machines and multi-adapter setups.

Key settings

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

stack chooses the userspace protocol stack implementation: system performs well but has average compatibility, gvisor is more compatible with slightly lower throughput, and mixed lets the kernel choose per situation. auto-route has the kernel write the routing table automatically; auto-detect-interface identifies the physical outbound adapter — both matter especially on machines with multiple adapters, since turning them off often sends return traffic out the wrong adapter, which shows up as a connection that works but is extremely slow or keeps dropping. dns-hijack intercepts DNS queries sent to port 53 and hands them to the kernel, which is the precondition for DNS not leaking under TUN mode.

DNS and Fake-IP

Under TUN mode, DNS must be handled by the kernel; otherwise apps resolve real IPs themselves and domain matching in your rules stops working.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "+.pool.ntp.org"
  nameserver:
    - 223.5.5.5
    - 119.29.29.29

How Fake-IP works: when the kernel receives a DNS query it immediately returns a fake address in the 198.18.x.x range and records which domain that fake address maps to. When an app connects to the fake address, the kernel looks the domain up in the mapping table and matches rules by domain. There are two benefits: rule matching is always domain-based, even if the app resolves before connecting, and one real lookup wait is eliminated, so the first connection is faster.

Domains listed in fake-ip-filter bypass Fake-IP and get real addresses. LAN device names, NTP time servers and some LAN services that need real IPs must go in there, otherwise you get odd symptoms like web pages loading while LAN devices are unreachable. nameserver should point to a DNS server reachable locally, not to an address that is itself proxied, or the query loops back to you and creates a cycle.

Common problems

• No internet at all after enabling: first check the log to see whether the virtual adapter was created, then whether auto-detect-interface identified the physical adapter correctly, and finally whether another VPN is fighting for the route.
• Some apps misbehave: add them to fake-ip-filter, or route them direct in your rules.
• UWP apps do not work on Windows: UWP apps run inside an app container and need loopback exemption enabled for them; most clients provide a switch for this.
• Conflicts with virtual machines: a VM's virtual adapter is affected by TUN's routing rules, so add that adapter to the exclusion list or use the two at different times.

The full troubleshooting order for node timeouts is in the blog post Clash Node Timeout and Connection Failures.

Daily maintenance: updates, logs and multi-device sync

Subscription updates

How often to update depends on how often your provider changes nodes; once a day is a common setting. After an update the client reloads the config and connections in progress are briefly interrupted. If the node list has not changed for a long time, trigger an update manually first and check what the log returns; if the update succeeds but the nodes are unchanged, the provider genuinely has not adjusted anything.

Logs and the connections panel

log-level runs from silent through error, warning and info up to debug, each level more verbose than the last. When troubleshooting, switch to debug temporarily and watch what the kernel actually decides when a connection is established — which rule matched, which outbound it took, whether a lookup failed. Keep it at info day to day; debug greatly increases log volume and will slow down low-powered devices if left on.

The interface exposed by external-controller can be read by dashboards to inspect the matched rule, outbound node and up/down byte counts for each connection. To judge whether rules work as intended, the connections panel beats the log: find the connection, look at the rule index and outbound group it matched, and compare with what you wrote.

Multi-device sync

Shared subscription link: every device imports the same link and the node list stays consistent automatically. This suits setups that are mostly about nodes with few local customizations; the price is that each device's rule settings are independent, so a change on one does not reach the others.

Self-hosted config: maintain one complete config yourself and have every device pull the same address, so rules and policy groups are identical. This suits multi-device setups with complex rules and has the highest maintenance cost — a broken config affects every device.

Manual export and import: send the config file to other devices over the LAN or cloud storage. This suits setups that rarely change, and works well as a backup for the first two approaches.

Resource usage and stability

The number of rule entries directly affects how long each connection takes to match. A few thousand rules are imperceptible on desktop, but on low-powered devices such as routers you need to keep the scale in check and split large rule blocks into RULE-SET files loaded on demand. The GEOIP database ships with kernel updates and does not need manual replacement. Memory usage relates to active connections and DNS cache size; if memory keeps growing after long uptime, first check whether a lot of url-test groups are testing frequently, or whether the log level has been left at debug.

A full comparison of the three multi-device sync approaches is in the blog post Clash Multi-Device Config Sync.

Advanced path: kernel features, self-hosted configs and troubleshooting

What mihomo changed

mihomo extends the original Clash with more inbound types, rule types and DNS capability: more inbound protocols, more rule matching dimensions (process, rule set, logical combinations), finer DNS policies and a more complete TUN implementation. When a subscription contains fields the original kernel does not recognize, switching to a mihomo-based client will parse them. The original Clash kernel is no longer maintained, so for long-term use it is best to start with a mihomo-family client.

From subscription user to config maintainer

The first step toward advanced use is treating a subscription as a node source rather than a complete config. The method was given in chapter 4: pull nodes in with proxy-providers and write the rules, policy groups and DNS yourself. The benefit is that switching providers only means changing the provider URL, with the rule system untouched, and rules can be tuned to your own habits instead of being limited by the provider's defaults.

The second step is understanding how to maintain rule sets: split large rule blocks into external files referenced by RULE-SET, update them regularly, and keep the main config lean. The upside of rule sets is that updates do not touch the main config; the downside is an extra file dependency, and a wrong path fails silently.

The third step is putting your config under version control: keep a backup before every change and write down what changed. When a config breaks you can roll back quickly, which is far faster than comparing line by line.

A reusable troubleshooting order

1. Subscription: did the last update succeed, and is the node list empty?
2. Nodes: switch to global mode and test a single node to rule out the rules.
3. DNS: is Fake-IP on, is the filter catching something it should not, does resolution work?
4. Ports: is the local port taken by another program?
5. System proxy or TUN: does the switch state match what you actually expect?
6. Rules: is the policy group shown in the connections panel the one you expected?
7. Logs: compare the observations from the six steps above with the log to find the layer that is actually broken.

The value of this order is that each step rules out one class of cause instead of casting doubt on everything at once. If all seven steps still leave you offline, the problem is lower down (physical network, server side, system firewall), and you can take the log to your provider or the client community for help.

Where to go deeper

• Kernel configuration docs: understanding the default of each setting is more useful than memorizing recommended values.
• The rule set ecosystem: learn how common rule sets are maintained and how often they update, and pick sources that are actively maintained.
• Networking fundamentals: the DNS resolution chain, the routing table and the TCP handshake — the three most useful areas of knowledge for troubleshooting.
• Automation: use scripts to manage config versions and rule updates, and keep a record of changes.

A detailed comparison of the kernels is in the blog post mihomo Kernel vs Original Clash; the first-install checklist is in the blog post Clash First Install and Initial Setup. To compare clients first, go to the client selection guide; once you have decided, grab the installer for your platform from the download page, and walk through the first setup with the Quick Start Guide.