Clash From Zero to Advanced: The Complete Configuration Manual

01 · Core Concepts: Core, Config File, and Subscription

Let's draw a clear line between three terms first, since every later chapter builds on them. The core is the command-line program that actually handles network traffic — the mainstream core today is Mihomo (a continuation of the Clash Meta project), which reads a config file and decides where each connection goes based on the rules inside it. The client is the graphical shell wrapped around the core, handling day-to-day tasks like importing subscriptions, switching nodes, and toggling the system proxy; Clash Plus, Clash Verge Rev, and FlClash on the download page all belong to this layer. A subscription is a URL your provider gives you — the client periodically pulls a node list and preset rules from it, then assembles the final config handed to the core.

The core only accepts one kind of input: a YAML config file, usually named config.yaml. It has a fixed top-level structure, with commonly used fields falling into four groups:

• Global parameters like mixed-port, allow-lan, mode, and log-level, which set the listening port and run mode;
• proxies: the node list, where each entry is a proxy server's address, port, protocol, and credentials;
• proxy-groups: policy groups, which bundle nodes into switchable sets like "manual select" or "auto speed test";
• rules: routing rules, matched top to bottom, deciding which policy group each connection lands in.

A minimal, working global parameter block looks like this:

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

mixed-port: 7890 means the core listens on port 7890 on localhost for both HTTP and SOCKS5 proxy traffic — point your system proxy settings there. allow-lan controls whether other devices on your local network can connect through it; it's off by default for home setups. mode sets the run mode, covered in Chapter 5. log-level controls how verbose the logs are — switch it to debug when troubleshooting, and leave it at info otherwise.

The relationship between subscriptions and config files is worth spelling out: what a subscription link returns might be a complete Clash YAML file (usable right away), or it might be a Base64-encoded node list (needing the client or a conversion service to fill in the policy groups and rules). The differences between the two formats, and how to convert between them, are covered in Clash Subscription Formats Explained. In everyday use you'll rarely write config by hand — the client assembles it for you — but understanding the structure is a prerequisite for editing rules, enabling TUN, and making incremental changes later on. Whenever you hit an unfamiliar term, check the glossary, which organizes common terms under categories like "Core & Protocols," "Rules & Routing," and "Exit Strategies."

One last point that trips people up: the original Clash project is no longer maintained, so "Clash" today usually refers to the whole ecosystem — the Mihomo core plus various graphical clients. On the protocol side, Mihomo supports Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and other mainstream protocols — whatever protocol your subscription's nodes use, the core just handles it, no need to switch software by protocol. That's one of the main reasons to pick a Clash-family client: one subscription covers multiple protocols, with unified rule-based routing on top.

02 · Client Picks: Matching Platforms to Needs

The client shapes your day-to-day experience; the core sets the ceiling on what's possible. Every mainstream client today bundles the Mihomo core, so capability differences are minor — picking one mostly comes down to platform coverage and interface style. The table below lists the options per platform and this site's recommended order, matching the shelf on the download page:

Here are three picks based on how you'll use it. First time using Clash, don't want to dig into config: just install Clash Plus. It's available on all five platforms, with subscription import, mode switching, and node speed tests all in one interface — the defaults work out of the box, and multi-device users get a consistent experience across all their machines. Need fine-grained control over config: Clash Verge Rev exposes the most core parameters, supports incremental config overrides (covered in Chapter 9), and puts the TUN toggle and core logs right at the top level of the UI — a good fit if you're willing to read the docs. Want something lightweight on Android: Clash Meta for Android has the simplest interface and lowest background overhead; FlClash stands out for cross-platform consistency, with one interaction model spanning desktop and mobile.

Two things to avoid. First, don't install Clash for Windows or ClashX Meta just because older tutorials still recommend them — both are unmaintained, stuck on old core versions, and may fail to recognize newer protocol nodes (like Hysteria2) outright, with no fixes coming. Second, there's no need to run multiple clients on one device — they'll all try to bind port 7890 and take over the system proxy, which inevitably conflicts if run at the same time; if you genuinely need to compare them, fully quit one before starting the other.

For the full breakdown of client selection — core version strategy, TUN support levels, config method differences, and detailed conclusions for "beginner / multi-device / power user" profiles — see the client comparison page and the article Mainstream Clash Clients Compared. The rest of this manual describes actions using Clash Plus and Clash Verge Rev as the reference; other clients use slightly different menu wording, but the concepts and workflow are identical — find the "subscription/config" entry to import, find the "mode" entry to switch, and find the "system proxy/TUN" toggle to take over traffic.

03 · Installation and First Launch

Get every installer from the download page — switch to your platform's tab, then pick the matching client and architecture. This chapter walks through the install steps per platform, the system prompts you'll hit on first launch, and where each platform keeps its key directories.

Windows

Run the installer and follow the wizard. On first run of an unsigned or newly-signed installer, SmartScreen might pop up "Windows protected your PC" — click "More info," then "Run anyway" to continue. Once installed, launch it from the Start menu; the client sits in the system tray, so check there first if you can't find the window instead of relaunching it. The first time you enable the system proxy or TUN, it'll trigger a UAC prompt asking for admin rights — allow it. If it errors out with bind: address already in use on launch, another program is holding port 7890 — see What to Do When Clash's Port Is Already in Use for the fix. Config and log files usually live under %USERPROFILE%\.config or the app data folder — the client's "open directory" menu takes you straight there.

macOS

Open the dmg and drag the app into your Applications folder. Note that installers come in Intel and Apple Silicon builds — check your chip type under "About This Mac" before downloading, since the wrong architecture will run noticeably slower or fail to launch. On first open, Gatekeeper may warn that the app was downloaded from the internet — click "Open" in the prompt, or go to "System Settings → Privacy & Security" and click "Open Anyway" at the bottom. Enabling the system proxy writes to your network preferences and may ask for your login password; enabling TUN requires installing a system extension or authorizing a helper tool — allow each prompt as it appears. The config directory defaults to a client subfolder under ~/.config.

Android

If installing the apk warns that installing from unknown sources isn't allowed, go into system settings and grant your browser or file manager permission to "install unknown apps." The first time you connect, Android will pop up a VPN connection request — this is the standard mechanism Android uses to hand over traffic, and you must allow it or the proxy won't take effect. On phones running heavily customized Android skins (MIUI, ColorOS, etc.), be sure to add the client to the battery optimization whitelist and allow background activity, or the process gets killed after the screen locks for a while — showing up as "it works, then randomly disconnects."

iOS and Linux

On iOS, install Clash Plus from the App Store — the first launch triggers a configuration-profile-style VPN authorization prompt, which you just need to allow. On Linux desktop distros, install Clash Verge Rev via the deb package (sudo apt install ./package-name.deb); enabling TUN requires granting the core network permissions, which the client's settings page can do for you with one click. On headless servers, download the Mihomo core binary directly and run it with systemd — that's covered as advanced material in Chapter 9.

Whichever platform you're on, do three things right after first launch: open the logs page and confirm there are no red errors; note where the config directory is (you'll need it for backups and troubleshooting); and leave the default port and DNS settings alone for now — the defaults work for the vast majority of setups, and changes should only happen once you clearly know why. If the client crashes the moment you open it, work through Fixing Startup Crashes and Instant Exits starting from the logs.

04 · Subscription Import and Updates

Your subscription link comes from your provider, usually found in their user dashboard under "Subscription" or "One-Click Import," in a format like https://example.com/api/v1/client/subscribe?token=xxxx. This URL is equivalent to your account credentials — leaking it to someone else is the same as sharing your account — so don't post it in public, and blur it out in screenshots.

Three Ways to Import

1. URL import (recommended): paste the link on the client's "Subscription/Config" page and hit import. The client remembers the address, so afterward you can update with one click, set it to refresh on a schedule, and have node changes sync automatically. This is the only method that keeps things "continuously synced."
2. File import: drag in or select the YAML file your provider gave you directly. Works fine offline, but the downside is you have to manually swap the file whenever nodes are updated.
3. Clipboard / QR code import: common on mobile — under the hood it's still URL import, just entered a different way.

How to tell import succeeded: the subscription entry expands to show a node list, and the policy group page shows the groups. If import fails, narrow it down in three steps: first open the subscription link directly in a browser — seeing a block of YAML or Base64 text means the link itself is valid; then check the client's error message keywords — something like invalid syntax points to a format mismatch, while a timeout points to a network issue; finally confirm the subscription format matches the client — some providers offer different link formats for different clients, so pick the "Clash" one. Some providers also check the request's User-Agent and only return YAML to Clash-family UAs, so seeing garbled text in a browser is expected behavior.

Update Strategy

Importing a subscription isn't a one-and-done thing — providers change node domains and ports over time, and nodes in an old config gradually stop working. It's worth setting the client's auto-update interval to 12 or 24 hours; if you run into "it worked yesterday, everything's timing out today," your first move should be to manually update the subscription. When an update fails, watch out for a chicken-and-egg problem: the subscription URL itself might need a proxy to reach — most clients offer an "update through proxy" toggle, which you can turn on while any nodes still work; if everything's down, your only option is to switch networks (like a phone hotspot) to update.

Subscription Conversion

When the subscription format doesn't match what the client expects (say, you get a generic Base64 node list, but the client only reads full YAML), it needs to go through a subscription conversion service: the converter pulls the raw subscription, applies a rule template, and outputs a standard Clash config. The mechanics of conversion, the privacy risk of public conversion services (the converter can see your subscription contents), and self-hosted alternatives are all covered in Clash Subscription Formats Explained. As a rule of thumb: if the client can already read your subscription directly, skip the converter — the shorter the chain, the more reliable it is.

For anyone managing multiple subscriptions: give each subscription its own config entry, rather than manually merging nodes from different providers into one file — a merged file can't be updated selectively, and it's harder to tell where a problematic node came from during troubleshooting. When you actually need to aggregate nodes across subscriptions, use the proxy-providers mechanism (Chapter 9) to have the core pull and merge them at runtime, rather than editing a static file.

05 · Proxy Modes: Rule, Global, and Direct

The core runs in three modes, corresponding to three values of the mode field in the config file — usually shown as a set of radio options in the client UI:

You should stay on Rule mode day to day. Its value is in routing: traffic to local sites goes direct, saving node bandwidth and avoiding extra latency; traffic to sites outside your region goes through the proxy; ad domains can be blocked outright. Global mode is a troubleshooting tool, not something to leave running — sending everything through the proxy means local traffic takes a detour too, which is both slower and doubles your bandwidth usage. A handy troubleshooting trick: if a site won't load, switch to Global mode and try again — if it loads now, the rules weren't matching correctly (go back to Chapter 6 to fix them); if it still doesn't load, it's a node problem (switch nodes, or see Layered Speed Troubleshooting).

Beyond Mode: How Traffic Reaches the Core

Mode determines what happens to traffic once it's inside the core — there's a separate switch controlling whether traffic reaches the core at all: the system proxy. When enabled, the OS points HTTP/HTTPS traffic at 127.0.0.1:7890, so browsers and most apps that respect system proxy settings work automatically. But some programs — command-line tools, certain games and client apps — don't read the system proxy, and their traffic bypasses the core entirely. This is the standard explanation for "my browser works through the proxy but my terminal doesn't," and there are two fixes: set proxy environment variables for that specific program (like HTTP_PROXY=http://127.0.0.1:7890), or go straight to system-wide takeover with TUN mode in Chapter 7.

Verifying Connectivity

Once you've picked a mode, verify three things in order: the client's "Connections" page shows active connection entries, confirming traffic is actually reaching the core; the exit column on those entries shows the expected policy group and node, confirming rules are matching correctly; and a site outside your region actually loads in the browser, confirming the whole chain works end to end. Whichever step breaks is where you should look — that's the core methodology behind all troubleshooting on this site: locate the layer first, then make changes. Which type of policy group you use (manual selection vs. auto speed test) directly affects the experience, and the differences between group types are covered alongside rules in the next chapter.

06 · Rule Routing: Syntax, Priority, and Policy Groups

Rules are Clash's core capability, written in the config's rules list, each in a three-part format: TYPE,VALUE,EXIT. The core checks each new connection top to bottom, stopping at the first match — order is priority, and that's the key to understanding and debugging every routing issue. Common rule types:

A complete rule block example, with comments marking the ordering logic:

rules:
  # Exact rules first: highest-priority manual overrides
  - DOMAIN-SUFFIX,openai.com,PROXY
  - DOMAIN-SUFFIX,github.com,PROXY
  # LAN and reserved addresses go direct; no-resolve avoids triggering DNS resolution for plain domain connections
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  # Geo fallback: local IPs go direct
  - GEOIP,CN,DIRECT
  # Final fallback: anything that didn't match above goes through the proxy
  - MATCH,PROXY

Three syntax points worth knowing. First, DOMAIN-SUFFIX,github.com matches both github.com and api.github.com, but not github.io — suffix matching stops at the dot boundary. Second, GEOIP and IP-CIDR match against the destination IP, so if the connection target is a domain, the core has to resolve it via DNS first before it can compare — adding no-resolve to LAN-range rules avoids forcing early DNS resolution on every domain connection, cutting down latency and DNS leakage. Third, nothing after MATCH ever runs, so any new rule must go before it — the first thing to check when "a rule change isn't taking effect" is whether an earlier rule is catching the connection first; the client's "Connections" page shows exactly which rule each connection matched, and that's the source of truth.

Policy Groups: Where Rules Point

The exit in the third part of a rule, aside from the built-in DIRECT and REJECT, usually points to a policy group. Policy groups bundle nodes into switchable sets, with four common types: select for manual picking — whatever you click is what's used; url-test, which periodically pings a test URL and auto-picks the lowest-latency node; fallback, which takes the first available node in list order, auto-downgrading if the top pick goes down; and load-balance, which spreads connections across multiple nodes. Example:

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

This structure is a common best practice: PROXY is the main entry point that rules point to, set to manual select; its first option is the auto speed-test group AUTO — pick it for day-to-day auto-optimized routing, and switch manually to a specific node for special needs (like a fixed region). interval: 300 means it retests every five minutes. Most subscriptions already come with a similar grouping structure built in — once you understand this pattern, you'll be able to read any subscription config, and you'll be set up to start editing config yourself in Chapter 9.

07 · TUN Mode and System-Level Takeover

Chapter 5 mentioned the blind spot of the system proxy: programs that don't read the proxy settings bypass the core entirely. TUN mode solves this at a lower level — the core creates a virtual network interface, and the OS's default route points to it, so all IP traffic (whether or not the program supports proxies, whether TCP or UDP) hits the core first, then gets routed by the rules. Command-line tools, games, UDP voice calls — all covered. The trade-off is it needs higher system privileges, and it conflicts with other software that also modifies routing.

Config and Parameters

Mainstream clients all expose TUN as a simple toggle (in Settings for Clash Verge Rev, under connection method options for Clash Plus), and behind that toggle is this config block:

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

Breaking it down: stack is the network stack implementation — system uses the OS's own network stack, offering the best compatibility and the right default for most cases; gvisor is a userspace stack worth trying if your system stack is acting up; mixed splits the difference. auto-route lets the core write routing table entries automatically and clean them up on exit — it must stay on, or traffic won't reach the virtual interface. auto-detect-interface automatically identifies the real outbound network interface, preventing traffic from looping back through the virtual interface. dns-hijack intercepts all DNS queries headed to port 53 and routes them through the core, keeping domain-based rules working correctly under TUN — without hijacking DNS, apps might resolve IPs on their own and connect directly, breaking every domain-based rule.

Permission Requirements by Platform

On Windows, first enabling it triggers an admin permission prompt and installs a virtual network adapter driver — allow the UAC prompt; if the whole machine loses internet afterward, the driver install was likely incomplete, so restart and try enabling it again. macOS requires authorizing a system extension under "System Settings → Privacy & Security" — newer macOS versions may also need confirmation under "Login Items & Extensions." Linux requires granting the core binary the CAP_NET_ADMIN capability, which Clash Verge Rev's settings page has a one-click button for. Android and iOS clients already run as VPN services by default, which is functionally equivalent to TUN — no extra setup needed.

Boundaries and Common Pitfalls

• TUN and the system proxy don't need to be on at the same time. After enabling TUN, it's best to turn off the system proxy — otherwise traffic gets handled twice, which just makes troubleshooting harder.
• TUN conflicts with other VPN or virtual-adapter software — two programs fighting over the default route usually results in no internet. Quit any other VPN-type software before enabling TUN.
• Once enabled, all traffic runs through the core, so rule quality directly shapes the experience: a direct fallback like GEOIP,CN,DIRECT must be in place, or heavy local traffic like system updates and cloud sync will all get routed through the proxy.
• If you're still offline after closing the client, it's leftover routes that weren't cleaned up — restarting the network interface or the whole system fixes it; see the troubleshooting section of the Help Center for more on this kind of issue.

The short version: if you're mostly a browser user, the system proxy is enough and keeps permissions minimal; if you need to cover command-line tools, games, or any UDP-based app, go with TUN — once it's set up, it's a "set and forget" stable state.

08 · Ongoing Upkeep: Updates, Backups, and Quick Diagnosis

Once everything's configured, Clash needs very little day-to-day maintenance — but a few things done on a schedule will help you avoid most "it suddenly stopped working" moments.

Three Kinds of Updates

Subscription updates happen most often: beyond turning on auto-update (every 12–24 hours), any time you see a whole batch of nodes timing out, manually update the subscription first before troubleshooting further. GeoIP / Geosite database updates are easy to overlook: the GEOIP,CN rule from Chapter 6 relies on a local IP geolocation database, and an outdated database can misclassify local IPs as foreign, sending them through the proxy unnecessarily — showing up as "local sites suddenly got slower for no reason." Mainstream clients offer a one-click update for this in settings; it's worth doing every month or two, and restarting the core afterward to apply it. Client and core updates: clients usually have a built-in update checker — back up your settings (see the next section) before upgrading; if you're not after new features, there's no need to upgrade a stable, working version frequently.

What to Back Up, and How

Only three things are worth backing up: the subscription link itself (store it in a password manager — with it, you can rebuild everything on any new device), any config or override snippets you've manually edited, and an export of your client settings (if the client offers one). You can also just zip up the whole config directory, but caches and logs aren't worth keeping. The standard flow for switching devices: install the client on the new device → paste in the subscription link → restore your custom snippets. Done in five minutes, no binaries to migrate.

Logs: Where Troubleshooting Starts

Every troubleshooting session should start with the logs, not with guessing. The client's logs page shows the core's runtime output: error-level lines spell out exactly what failed (port conflicts, config syntax errors, node handshake failures), and info-level lines show the matching process for each connection. If the in-app logs aren't detailed enough, the full log files live in the config directory. Temporarily bumping log-level to debug shows every step of DNS resolution and rule matching — just remember to switch it back to info afterward, since debug logs pile up fast.

Quick Diagnosis Table

The fourth row's "system clock drift" deserves special mention: protocols like VMess are sensitive to timing, and if your local clock is off by more than about 90 seconds, the handshake fails outright — every node using that protocol times out at once, which looks a lot like the subscription itself being dead. Add "is the system clock syncing automatically" to your routine checklist. For more scattered Q&A-style content, check the Help Center, organized into basics, install & config, usage tips, and troubleshooting.

09 · Advanced Setups: Overrides, External Control, and Running the Core Directly

Once you've worked through the first eight chapters, you've got everything you need for daily use. This chapter offers three paths for going deeper, ordered from least to most effort.

Path One: Config Overrides Without Touching the Subscription

Directly editing the config file generated from your subscription is a common beginner mistake — the next time the subscription updates, your changes get wiped out. The right approach is an override: write your changes as a separate snippet, and the client automatically merges them into the final config after every subscription update. Clash Verge Rev supports both YAML merge and script-based overrides, with typical uses like: inserting your own high-priority rules ahead of the subscription's rules, appending a self-hosted node, or forcing a saner speed-test interval than what the subscription ships with. Here's a minimal merge override that appends two rules to the top of the rules list:

prepend-rules:
  - DOMAIN-SUFFIX,internal.example.com,DIRECT
  - DOMAIN-KEYWORD,tracker,REJECT

In the same "let something else manage it" spirit as overrides, there's proxy-providers / rule-providers: they let the core pull node sets and rule sets from a URL at runtime and refresh them on a schedule, with the main config just holding a reference. Aggregating multiple subscriptions, or pulling in community-maintained rule sets (like ad-domain lists), both rely on this pair of mechanisms rather than manual copy-pasting.

Path Two: The External Control API

The core ships with its own HTTP control interface, enabled with two lines in the config:

external-controller: 127.0.0.1:9090
secret: "your-password"

Once enabled, switching nodes, changing modes, checking connections, and testing latency can all be done through HTTP requests — the client UI is, at its core, just a front end for this API. What this unlocks: managing the core from a browser using a web dashboard (most clients have a built-in link to one); writing scripts that test speed on a schedule and auto-switch policy groups; or remotely managing a headless core running on a home server. Two non-negotiable security rules: secret must be set and sufficiently random, and the listening address should stay at 127.0.0.1 — if you genuinely need LAN access, restrict the source with a firewall.

Path Three: Running the Mihomo Core Directly From the Command Line

For headless setups like servers, routers, or NAS boxes, skip the graphical client and run the core directly. The core section of the download page has binaries for every architecture; the basic usage is mihomo -d /etc/mihomo, where -d points to a directory containing config.yaml and the geo database. Pair it with a systemd unit for auto-start on boot and restart on crash, then manage it remotely using the control API from Path Two — and you've got the beginnings of a whole-house routing gateway. This path assumes you've fully absorbed the config structure from Chapters 1 through 6 — and at this point, the "zero to advanced" loop is complete.

A Suggested Learning Order

1. Test the rule syntax from Chapter 6 on your own config: add a rule, then confirm it's matching on the Connections page.
2. Use overrides to lock in your regular tweaks, and get a feel for a workflow where subscription updates never wipe out your changes.
3. Turn on external control and spend a day driving the core through a browser dashboard instead of the client UI, to get a feel for where the core ends and the interface begins.
4. If you've got a spare device, try running the core from the command line and carry over what you've learned on desktop to a server setup.

Each step builds on the one before it — there's no need to skip ahead. When you hit an unfamiliar term, check the glossary; when you hit a specific issue, check the quick diagnosis table in Chapter 8; when you're unsure which client to pick, check the comparison page — treat this manual as a wiring diagram to keep close at hand.