The Complete Clash Manual

01Core Concepts: Core, Client, and Config File

Clash is a rule-based proxy framework built from two layers: a core that does the actual traffic forwarding, and a client that provides the graphical interface. The original core project is no longer developed; the core that's actively maintained in the ecosystem today is mihomo (the community still commonly calls it the Clash Meta core), which stays compatible with the original config format while adding support for more transport protocols. What people mean by "installing Clash" is really installing a GUI client that bundles the mihomo core — Clash Plus, Clash Verge Rev, and FlClash all fall into this category. Their interfaces differ, but they read the same underlying config format.

What a config file looks like

Everything the core does is governed by a single YAML config file. Understanding its skeleton is the foundation for every chapter that follows. A minimal working config generally has these sections:

mixed-port: 7890        # Local listening port shared by HTTP and SOCKS
allow-lan: false        # Whether devices on the LAN can connect
mode: rule              # Run mode: rule / global / direct
log-level: info

proxies: []             # Node list, usually generated from a subscription
proxy-groups: []        # Policy groups: decide which traffic uses which node
rules:
  - MATCH,DIRECT        # Rule list, matched top to bottom

proxies lists the available nodes, proxy-groups organizes those nodes into switchable groups, and rules decides which group each connection lands in. Maintaining these three sections by hand is tedious, so most users rely on a subscription: the provider gives you a URL, the client fetches it periodically, and you get a fully generated config back. A subscription is really just a "remotely hosted config file" — more on that in Chapter 4.

Local port and system proxy

Once the core starts, it listens on a local port (7890 is the common default). Applications send traffic to 127.0.0.1:7890, and the core decides, per rule, whether to go direct or through a proxy. The "system proxy" toggle in the client simply points the operating system's proxy settings at that port. Understanding this "listening port + system proxy" relationship makes it much easier later to troubleshoot the classic "Clash is on but nothing changed" situation.

02Choosing a Client: Platform Comparison and Recommended Order

Available clients differ by platform, and their feature focus varies too. The table below lists, by platform, the clients featured on our downloads page, in the same order as that page:

How to choose

Clash Plus is the top recommendation across the board: it's available on all five major platforms with a consistent interface, and common actions — subscription import, switching policy groups, the TUN toggle — sit right up front, making it the easiest for newcomers to learn. Clash Verge Rev has the deepest feature set on desktop, supporting config overrides, Merge scripts, and an external control panel — a good fit for users who want deeper customization, and this site has dedicated Clash Verge Rev tutorial articles as well. FlClash is built with Flutter and offers a consistent experience across desktop and mobile; pick it if you prefer a clean interface. Clash Nyanpasu is Windows-only and positioned similarly to Verge Rev.

Once you've picked a client, the terminology in later chapters may be labeled slightly differently in each app (e.g., "subscription," "config," "Profiles"), but the workflow is the same. This manual uses generic terms throughout and calls out client-specific differences where they matter.

03Installation: Platform Notes and Common Blocks

Installation itself is straightforward — what trips people up is each OS's built-in security layer. This chapter walks through install steps per platform along with how to get past each block.

Windows

Download the exe installer from the downloads page and double-click to run it. On first run, SmartScreen may show "Windows protected your PC" — a generic warning for unsigned or low-download-count apps. Click "More info → Run anyway" to continue. Keep the default install path; if your antivirus flags the core binary as suspicious, add the install folder as a trusted location in your AV software — the core creates a virtual network adapter and a local proxy port, and this kind of behavior often triggers heuristic false positives. After installation, it's worth enabling "Launch on startup" in the client settings and running it once as administrator, which makes enabling TUN mode easier later.

macOS

Download the dmg or zip and drag it into the Applications folder. Pay attention to the chip variant: pick the arm build for Apple Silicon and the x64 build for Intel Macs — installing the wrong one either fails to launch or runs under a translation layer with a performance hit. If you see "cannot verify developer" the first time you open it, go to System Settings → Privacy & Security, scroll to the bottom, and click "Open Anyway." If you see "file is damaged," it's usually because the download got tagged with a quarantine attribute by the OS — run this in Terminal, then reopen it:

xattr -dr com.apple.quarantine /Applications/ClientName.app

The first time the client turns on the system proxy or TUN, macOS will ask to install a helper tool or network extension — enter your password when prompted to allow it. This is a one-time step.

Android

Choose the APK by CPU architecture: pick the arm64 build for recent mainstream devices, or the universal build for older or unknown-architecture devices (larger file, but compatible with any architecture). During install, Android will ask you to allow "install unknown apps" — grant this once for your browser or file manager. The first time you start the proxy, a VPN connection request pops up — you must allow it, since Android clients take over traffic through the system's VPN interface, and denying the request means the proxy simply won't work. Some manufacturer skins aggressively kill background apps, so it's worth setting the client to "unrestricted" in battery settings and locking it in recent apps.

iOS

On iOS, install Clash Plus from the App Store — search for it directly or use the store link from the downloads page; app details are also listed on the official site, clashplus.io. The first time you start the proxy after installing, you'll be asked to allow adding a VPN configuration — confirm in the system prompt.

Linux

On Debian/Ubuntu, use the deb package: sudo apt install ./package-name.deb. On Fedora, use the rpm package: sudo dnf install ./package-name.rpm. GUI clients require a desktop environment; on a headless server it's more practical to run the mihomo core directly — see Chapter 9. Enabling TUN requires granting network-management capability to the binary, or running as root; client settings usually offer a one-click way to grant this.

04Subscription Import: Getting, Importing, and Update Strategy

Subscription links are issued by your proxy provider through their user panel, usually labeled "Clash subscription" or "Clash config." Make sure you copy the full URL, not the panel's own address. Some providers offer multiple formats — pick Clash or mihomo format.

Import steps

1. Copy the subscription link from your provider's panel. The link contains an access token equivalent to your account credentials — never share it or post it publicly.
2. Open the client's "Subscription" or "Profiles" page, click add/import, paste the link, and confirm. The client downloads and parses it immediately, and on success a new profile entry appears showing traffic usage and expiration.
3. Select that profile to make it the active config (some clients select it automatically after import). Switch to the "Proxies" tab — you should now see policy groups and node lists, confirming a successful parse.

Update settings

Subscription content changes as the provider adjusts nodes, so leaving it stale for a long time can eventually lead to every node timing out. There are three update-related settings in most clients: update interval (12–24 hours automatically is a reasonable default), update on launch (refresh the subscription every time the client opens), and update via proxy (fetch through a currently working node if the subscription domain itself is blocked). How to combine these and typical error scenarios are covered step by step in the blog post What to Do When Subscription Auto-Update Fails.

Troubleshooting a failed import

Import failures mostly trace back to six causes: an expired or data-exhausted link, copying something that isn't actually Clash format, the provider blocking your request's user agent, a YAML syntax error, the local network blocking the subscription domain, or a client version too old to recognize newer fields. A step-by-step checklist is in Subscription Failures & Parse Errors: A Troubleshooting Checklist. If the error message mentions "yaml" or "parse," suspect a format issue first; cross-checking with a different client is a quick way to tell whether the problem is the link itself or something local.

05Proxy Modes: Rule, Global, and Direct

The mode field in the config file takes three values, matching the three modes shown in the client's interface, which determine how the core handles every connection:

A common mistake is leaving global mode on long-term: it routes local traffic out through distant nodes too, making local services slower and burning through subscription data for no reason. Global mode's real purpose is as a diagnostic tool — if a site won't load in rule mode but works after switching to global, the problem is a rule that isn't matching, which should be fixed in Chapter 6, not worked around by staying on global permanently.

System proxy and its scope

Picking a mode is only half the job — traffic also needs to actually reach the core. On desktop, the most common entry point is the "system proxy" toggle: turning it on points the OS-level proxy setting at the core's mixed-port, and browsers plus most apps that respect system proxy settings will pick it up automatically. But system proxy is a "gentleman's agreement" — some command-line tools and apps that ignore the OS setting will bypass it entirely, and that traffic needs TUN mode (Chapter 7) to get captured. In a terminal you can set it manually via environment variables:

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890

Verifying the proxy actually works

Three checks: first, run a latency test on the node list to confirm the selected node isn't timing out; second, visit any IP-lookup site and confirm the reported exit IP matches the node's region; third, open the target site to confirm it loads. These three steps verify, in order, "the node works," "traffic is actually going through the node," and "the rule matched correctly" — a failure at any step narrows down where the real problem is.

06Rule-Based Routing: How Policy Groups and Rules Work Together

Rule-based routing is what sets Clash apart from a plain proxy tool, built from two cooperating sections: proxy-groups and rules. Policy groups answer "which exits are available," and rules answer "which traffic uses which group." A subscription-generated config already comes with routing baked in; this chapter explains how it works so you can read an existing config and modify it as needed.

Four common policy group types

• select: manual-selection group, switched by clicking in the client UI — this is what "node select" usually refers to;
• url-test: auto speed-test group, pings a test URL at a set interval and always picks the lowest-latency node;
• fallback: failover group, uses the first available node in list order and automatically moves to the next when one fails;
• load-balance: load-balancing group, spreads connections across multiple nodes.

Rule syntax and priority

Each rule follows the format "type,match-value,target-policy." Common types include DOMAIN-SUFFIX (domain suffix), DOMAIN-KEYWORD (domain keyword), GEOIP (IP geolocation), IP-CIDR (IP range), and the catch-all MATCH, which must be the last line. Rules are matched top to bottom, and stop at the first match — so order equals priority: put precise domain rules first, put GEOIP-style rules that require a resolved IP later, and finish with MATCH. A snippet showing the typical structure:

proxy-groups:
  - name: Node Select
    type: select
    proxies:
      - Auto Test
      - DIRECT
  - name: Auto Test
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    proxies:
      - HK Node
      - JP Node
  - name: Streaming
    type: select
    proxies:
      - Node Select
      - JP Node

rules:
  - DOMAIN-SUFFIX,netflix.com,Streaming
  - DOMAIN-KEYWORD,youtube,Node Select
  - DOMAIN-SUFFIX,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,Node Select

This snippet expresses three intents: streaming domains go to a dedicated "Streaming" group (which can pin a specific region's node for stable unlocking); cn-suffix domains and connections that resolve to mainland China IPs go direct; everything else falls through to "Node Select." Groups can reference other groups (the "Streaming" group includes "Node Select"), which gives the config a hierarchical structure — changing one upstream group affects everything that references it.

For a full worked example — separate groups per streaming platform, and common rule-ordering pitfalls — see the blog post Rule-Based Routing in Practice: Grouping for Local vs. Remote Traffic.

07TUN Mode: Capturing All Traffic

Chapter 5 mentioned that the system proxy can't cover every program: apps that don't read the system proxy setting, some game clients, and command-line tools will bypass the core entirely. TUN mode solves this by creating a virtual network adapter at the OS level, intercepting all of the device's outbound traffic at the network layer and handing it to the core — completely transparent to applications, with no per-app proxy configuration needed. The VPN interfaces used by Android and iOS clients are essentially the same idea, which is why mobile has no separate "enable TUN" step; this chapter focuses mainly on desktop.

Steps to enable it

1. Grant permission. Creating a virtual adapter needs elevated privileges: on Windows, run the client as administrator (or install the system service in settings to avoid needing elevation each time); on macOS, install the network extension when prompted the first time you enable it; on Linux, use the one-click authorization option in client settings for the core binary.
2. Toggle TUN on in the client settings. Once enabled, a new network adapter with "utun" or "Clash" in its name will appear in your system's network connections — that's confirmation it's working.
3. Turn off the system proxy toggle. TUN already captures traffic at a lower level, so keeping system proxy on adds nothing and can cause routing loops.

DNS configuration

Under TUN mode, DNS resolution is also handled by the core, so the config needs a working dns section — subscription-generated configs usually already include one, typically looking like this:

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

fake-ip is the recommended enhanced mode under TUN: the core first returns a virtual IP from a reserved range, then matches the domain against rules once the connection is actually established, skipping a real DNS lookup and making rule matching more reliable. If a specific case that depends on the real IP misbehaves (some LAN service-discovery scenarios, for example), you can add a fake-ip-filter exclusion for that domain.

08Routine Maintenance: Updates, Backups, and Quick Troubleshooting

Once everything's working, day-to-day upkeep is minimal — but a few habits meaningfully cut down on surprise breakage.

Keep three things current

Subscription: set the auto-update interval as covered in Chapter 4; if nodes start timing out en masse, manually refresh the subscription first before chasing other causes. Client: actively maintained clients keep pace with core and OS compatibility — grab the latest version from the downloads page and install over the existing one; your config and subscription won't be lost. Geo databases: GEOIP rules rely on GeoIP/GeoSite data files, and most clients offer a one-click update in settings — refreshing every few months is plenty.

What to back up, and how

What's actually worth backing up is your "subscription link + custom overrides" — with those two, you can rebuild your setup on a new device in minutes. The generated config file itself doesn't need backing up, since it can always be re-fetched. Desktop clients' config directory (which includes override files and app settings) can be copied wholesale for safekeeping; each client's settings page usually shows where that folder lives.

Read the logs to pin down issues

The client's log page prints the match result for every connection in real time, roughly in the form "domain/IP → matched rule → final exit." When a site isn't behaving as expected, search the log for its domain and you'll immediately see which rule it hit and which node it went through — far more effective than randomly switching nodes. Log verbosity is controlled by the config's log-level field; bump it to debug while troubleshooting and leave it at info otherwise.

Quick troubleshooting table

Anything not covered here is organized by category on the FAQ page — worth checking there first.

09Next Steps: From Getting By to Getting It Right

After the first eight chapters, day-to-day use should be friction-free. The directions below are ordered by practical value — dig into whichever ones you actually need.

LAN sharing

Set allow-lan to true in the config (the client UI usually has a matching toggle), and other devices on the same network — phones, TVs, consoles — can point their proxy settings at this computer's LAN IP plus the mixed-port number, sharing the same proxy and rules without installing a client on every device. For firewall rules and per-device setup, see the blog post Mixed Port & LAN Proxy Sharing Setup.

Overrides and Merge

As noted in Chapter 6, editing a subscription's config directly gets overwritten on the next update. The override mechanism writes your changes — extra rules, a replaced DNS section, a different port — into a separate file that the client layers on automatically every time the subscription loads, so the subscription keeps updating normally while your customizations persist. Clash Verge Rev has the most complete implementation, supporting both YAML merging and scripts; a good starting exercise is adding a single DOMAIN-SUFFIX rule for a domain your subscription doesn't already cover.

External control API

The core has a built-in RESTful control API. Once you declare external-controller: 127.0.0.1:9090 in the config, you can query and control the core over HTTP — the web-based control panels are built on top of this. For example, to list all current policy groups:

curl http://127.0.0.1:9090/proxies

Paired with scripts, this enables things like scheduled node switching or automated latency logging — a good fit for anyone with a bit of scripting background.

Running the core headless

Router or server setups don't need a GUI client — just run the mihomo core directly: grab the binary for your architecture from the core section of the downloads page, write a complete YAML config, and manage the process with systemd to provide transparent proxying for the whole network. This path involves routing and iptables/nftables knowledge, so it's worth mastering the rule system on desktop first before attempting it.

Where to go from here

For hands-on setup, go back to Quick Start and follow the main path. For filling gaps in understanding, check the FAQ. The blog post Ten Beginner Questions, Answered makes a good condensed version of this manual to pass along to someone just getting started. Clients and cores keep evolving, and this page gets updated as the ecosystem changes — worth bookmarking for reference.