Clash User Guide
Subscriptions & Rule-Based Routing Setup

01 Core Concepts: How a Connection Flows

The client, core, and proxy service are different things

In the Clash ecosystem, a client usually means a desktop or mobile app with a graphical interface for managing subscriptions, switching modes, and viewing connections. The core is the program that forwards network traffic and matches rules; Mihomo is a widely used core in this ecosystem. An open interface only confirms that the app launched. It does not mean the core loaded a configuration, or that network requests are being routed through the proxy. Troubleshooting is often more effective when you check each of these separately instead of reinstalling everything.

A proxy service provides the addresses, protocols, and credentials needed for remote connections. A subscription distributes that configuration. Installing a client does not provide a working service. Get a compatible configuration from a provider you are authorized to use, and follow applicable laws, service terms, and network policies. Subscription links may contain access credentials: never post them publicly or submit them to conversion sites you do not trust.

Understand the traffic entry point before the exit

A request typically follows four steps: an app sends it, the system proxy or a virtual network interface passes it to the core, a rule selects a policy, and that policy chooses a direct or remote connection. The system proxy is an operating-system setting for apps that choose to honor it. TUN is a virtual network interface that can capture more traffic, but routing, permissions, and exclusions still apply. Enabling it does not guarantee every app will work as expected.

A proxy node contains the parameters for a specific remote connection; a proxy group collects nodes or other policies for management. In a rule, PROXY is often the name of a proxy group, not a built-in keyword available in every configuration. DIRECT means connect directly, and REJECT means block the request. When a rule points to a name, check that it exists in the configuration and see what the group ultimately selects.

Why DNS and ports affect the outcome

DNS resolves domain names to addresses. A client may use the system resolver or the core's own DNS settings. Where resolution happens affects whether domain rules can match, which address-based rules apply, and whether a request must wait for a lookup. A failed connection does not automatically mean the node is down: DNS resolution failure, an unreachable resolved address, and a failed proxy handshake are different issues.

A port is the local endpoint number for a service. A mixed port usually accepts both HTTP proxy and SOCKS requests, but defaults vary by client. This guide uses 7897 as an example; always use the value shown in your client. A matching port number does not prove traffic reached the core. Also check the listening address, app settings, and whether another process already uses the port.

02 Choose a Client: Start with Your Platform and Maintenance Needs

Start with a graphical client that fits your device

For a first setup, consider Clash Plus, then compare other clients based on your platform and preferences. Don’t choose by appearance alone or install outdated software just to match a tutorial screenshot. Check supported operating systems, processor architecture, subscription compatibility, and access to the system proxy, logs, and TUN controls you need. Find installers on the Clash download page.

On Windows, consider Clash Plus, Clash Verge Rev, FlClash, or Clash Nyanpasu. On macOS, options include Clash Plus, Clash Verge Rev, and FlClash. On Linux, graphical clients include Clash Verge Rev and FlClash. Clients may share similar core capabilities, but service installation, overrides, and permission handling vary. This guide refers to features by name rather than treating one client’s button locations as universal.

How mobile and desktop clients differ

On Android, choose from Clash Plus, Clash Meta for Android, FlClash, or Surfboard as needed. Surfboard uses a configuration system that differs from Clash YAML, so not every Clash config can be imported with fields mapped one to one. Check which subscription formats your provider supports before choosing a client. Mobile operating systems typically route traffic through a VPN interface; the system permission request on first connection is part of that process.

On iOS, use the download page to find the Clash Plus App Store listing, or visit its website at clashplus.io. Background restrictions, per-app routing, and desktop system proxy settings work differently on phones. When working across devices, carry over the logic of your rules and configuration—not the menu labels. A shared subscription also does not mean every device can use identical runtime settings.

Run the client and core separately

Clash for Windows and ClashX Meta are no longer maintained and are listed on the download page as archived options. Existing configurations can help with migration, but for a new setup, choose a maintained client. Preserve your subscription source, rule intent, and proxy group selections during migration; don’t overwrite the new client’s entire data directory. Database formats, caches, and service registrations from older versions may not be compatible.

Mihomo core packages are mainly for users who are comfortable maintaining configurations, processes, and permissions themselves. They are not full graphical installers and do not handle every aspect of system integration automatically. If all you need is rule-based routing in a browser, a graphical client is the simpler place to start. For migrating an older setup, see Alternatives and Migration Options After Clash for Windows Reached End of Support, and check ports and proxy settings one by one.

There’s no need to install several clients at once just to compare them. Choose one as your primary client and quit the others so they don’t compete to change system proxy settings, routes, or DNS. Keeping the traffic path clear makes later test results easier to interpret.

03 Installation Checks: OS Architecture, Permissions, and Local Ports

Check your OS and processor architecture before downloading

Start by checking your operating system, processor architecture, and available storage in system information. Windows installers commonly target x64; macOS downloads differ for Intel and Apple Silicon; Linux packages also vary by distribution and package format. An ARM label does not mean one file works on every ARM device. Follow the architecture and client requirements on the download page. Don’t try to fix an incompatible package by renaming its extension or forcing it to unpack.

Quit older proxy clients and any other tools that may route network traffic before installing. If an old app launches at startup or runs as a background service, closing its window may not stop it; quit it from the system tray or menu bar. Note the old mixed port and subscription source for migration checks. Don’t delete the old configuration yet. Wait until the new client connects and passes verification before deciding what to remove.

Complete the first launch on your platform

On Windows, run the installer and launch the app normally. Grant elevated permissions only when required for service installation or TUN, as described by the client. Don’t run the entire app as an administrator by default. On macOS, move the app to Applications and launch it through the system-approved flow. If a security warning appears, check the source and warning details; don’t run unfamiliar terminal commands to disable system protections wholesale.

On Linux, install the package using the method appropriate for your distribution and resolve any dependency errors. Once the graphical app opens, check that the core status and logs are available. System proxy behavior can vary by desktop environment; failure to set a desktop proxy automatically does not necessarily mean the core cannot run. First distinguish an app launch issue from a core startup issue or system integration issue, then address the relevant layer.

Establish a clean startup baseline

After the first launch, check the mixed port, listening address, and LAN access setting. If the proxy is only for this computer, keeping access local is usually sufficient. This guide uses 127.0.0.1:7897 as an example endpoint. If your client shows a different port, use that value in subsequent app settings and commands. Save the configuration and check that the client reports no listening or port conflict errors.

# Windows PowerShell: check whether the example port is listening
Get-NetTCPConnection -LocalPort 7897 -State Listen

# macOS / common Linux environments: check the example port
lsof -nP -iTCP:7897 -sTCP:LISTEN

These are troubleshooting commands for the relevant operating systems, not commands to run on every platform. If no listener appears, check whether the core is running, whether it loaded a configuration, and whether the port number is correct. If a process is listed, verify its name; an open port alone does not prove everything is working. If a command is unavailable, use the system’s built-in resource monitor or client logs instead. There’s no need to install extra tools for a single check.

You don’t need to enable TUN, connect at startup, and every automatic update option during installation. First make sure the client launches, logs are readable, and the port is free; then move on to subscriptions. When troubleshooting, save the exact error and steps that triggered it rather than just noting that the app “won’t open.” At this point, aim for a minimal, repeatable local setup—not a stack of untested features.

04 Import a Subscription: From Link to Active Configuration

Get a compatible configuration, then update it

A subscription is an updateable configuration source, usually a remote link but sometimes a local YAML file. Ask your provider which clients or cores it supports. Then open the subscription, configuration, or Profiles page in your client and add a remote profile. Give it a recognizable name, paste the full link, save it, and update. Don’t omit parameters at the end of the link or mistake a webpage title for the actual subscription URL.

After an update succeeds, you usually still need to select and activate the configuration. Downloading and applying it are separate steps: a changed timestamp in the subscription list does not mean the running core switched to it. Check the active configuration name, core logs, and whether the expected proxy groups appear. If the old group names remain, check that the new configuration is enabled. Some clients manage multiple subscriptions, but how they combine them depends on the client’s own configuration system.

Distinguish the subscription, override layers, and runtime result

The original subscription is data provided by the service; an override adds or changes settings when the client loads it; the runtime configuration is what the core ultimately receives. Editing a downloaded cache by hand may work only until the next update overwrites it. For rules, ports, or DNS settings that must persist, use the client’s persistent override feature and check whether it runs before or after the subscription, or merges fields.

Not every remote configuration includes a complete set of rules. Some provide only nodes and rely on a client template to add proxy groups and rules; others already include DNS, rule providers, and full policies. Inspect the structure after import instead of deleting parts to match a tutorial. Proxy group names are referenced by rules: renaming a group without updating its references can cause the core to reject the configuration or leave policies ineffective.

# Structure example: illustrates fields; not a proxy service configuration
mixed-port: 7897
allow-lan: false
mode: rule

proxies: []

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

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

This YAML illustrates how configuration fields relate, but it contains no remote nodes, so all requests ultimately connect directly. Use it to read and check fields, not to test a proxy service. Server addresses, passwords, protocols, and certificate settings in a real subscription must come from a source you’re authorized to use; don’t piece them together from a tutorial. YAML uses spaces for indentation; inconsistent levels, tabs, Chinese colons, and unmatched quotes can all cause parsing errors.

Handle update failures by error type

For a network timeout, first check whether your current connection can reach the subscription service and whether updates need to go through an existing proxy. For an authentication error, check whether the link has expired and whether your service is active. If the response is a webpage rather than a configuration, you may have reached a login, error, or redirect page; ask your provider for the correct endpoint. If the download succeeds but parsing fails, check field compatibility and the reported error line instead of repeatedly switching nodes.

Local imports are useful for migration and offline backups, but usually don’t update automatically from the provider. Use remote subscriptions according to their validity period and update schedule; avoid refreshing them manually too often. Keep a recoverable local copy before updating. Afterward, verify that proxy groups, rules, and connections still work. Before sharing logs or screenshots, redact subscription links, server credentials, and personal browsing records. Hiding only the subscription name is not enough.

05 Proxy Modes: Configure Traffic Entry Separately from Routing

What rule, global, and direct modes control

Proxy mode determines how requests that reach the core choose an exit; it does not ensure that every app sends requests to the core. Rule mode evaluates the configuration’s rules one by one and is suited to everyday routing. Global mode sends requests that reach the core through the global policy, which can help narrow down an issue. Direct mode connects requests that reach the core straight to their destinations for comparison. Switching to global mode won’t suddenly capture apps that were bypassing the system proxy.

Global mode does not necessarily mean one fixed node. After switching, check which group or exit the global policy currently points to. In rule mode, check the selected policy group referenced by each matching rule. If a group contains DIRECT, selecting it means connecting directly—even while the interface still says rule mode. To understand what happened to a request, check its connection chain and matched rule, not just the mode label on the home screen.

Complete a first, explainable connection test

Start in rule mode, choose an exit you’re authorized to use in a proxy group, then enable the system proxy. Open a webpage you can use for testing and watch the connections page. If no new connection appears, check whether the browser has its own proxy settings, an extension is overriding them, or the request came from cache. Reload the page to trigger a fresh request if needed; don’t mistake an existing browser connection for a result after the change.

If a connection appears, expand its details to check the target domain, matched rule, and final policy. A page loading is only one outcome: it may have connected directly or through the proxy. Compare targets with known expected routes, such as a test domain explicitly set to direct and another explicitly set to use a proxy. Don’t infer how the whole network works from a single page load, or treat a region shown by an external site as definitive proof.

Set an explicit proxy for apps that ignore system settings

Some command-line tools do not automatically use the desktop’s system proxy. Configure a proxy in the tool itself or specify a local endpoint for a single command. The request below uses the example mixed port; replace the number if yours differs. It tests the HTTP proxy endpoint only and does not show whether UDP or TUN works. Results also depend on the destination site, current network, and selected policy.

curl --proxy http://127.0.0.1:7897 --head https://example.com

If a command cannot connect to the local port, return to the installation chapter and check the listener. If it reaches the proxy but the remote handshake fails, check the exit, credentials, and network restrictions. For a temporary global-mode test, note the original mode and proxy group, then restore rule mode afterward. Mode changes usually affect new connections; existing long-lived connections may keep using the old route. If needed, close the relevant connection and make a fresh request.

Build a consistent habit: first check whether traffic reached the core, then which rule routed it, and finally whether the exit works. Changing rules won’t help if no traffic enters the core. If the correct rule matches but the handshake fails, changing more rules only adds variables. For a shorter workflow, return to Getting Started and repeat the steps in order.

06 Rule-Based Routing: From First Match to Persistent Overrides

Rules are checked from top to bottom; matching stops at the first hit

The rule list does not evaluate every condition and combine the results. Typically, the core checks rules from top to bottom, and the first matching rule determines the policy; later rules do not affect that decision. Put specific exceptions that need priority before broader rules. MATCH is a catch-all rule and usually belongs at the end. If it appears earlier, later rules won’t get a chance to handle the requests it matches.

DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain and its subdomains, and DOMAIN-KEYWORD matches a keyword in the domain. They differ in scope and are not interchangeable just because one is shorter. Keyword rules in particular can match more than intended. For a single host, an exact domain rule is usually easier to verify and maintain.

# Assume the existing configuration contains a proxy group named PROXY
rules:
  - DOMAIN,docs.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

In this order, docs.example.com matches the exact-domain direct rule first; other matching domains with that suffix go to the proxy group. The private address rule handles the specified address range. no-resolve prevents this IP rule from actively triggering a domain lookup; it can still match when a request already has a destination IP. It does not disable DNS for the whole configuration, and you should not mechanically add the option to every address rule.

When address rules and rule sets apply

IP-CIDR matches IPv4 ranges; IPv6 ranges usually use IP-CIDR6. GEOIP makes decisions using an IP address database; IP geolocation does not necessarily match a company’s location or a visitor’s region. The database can also change. Whether a rule needs to resolve a domain or can use an existing address affects its behavior. If address rules appear before domain rules, pay close attention to DNS behavior and match logs.

RULE-SET references a rule provider declared in the configuration, making it useful for maintaining a set of rules separately. It is not shorthand for putting a remote URL directly in the rule list. The provider name, source, format, and behavior type must match. A plain domain list and a classical rule list use different formats; mixing them up can cause a load failure or ineffective rules. Start by understanding a few local rules before adding external rule sets.

Change the runtime result, not just the downloaded cache

When adding a rule, first find out whether the client supports rules inserted before or after existing rules, or a full override. If you append a custom rule after an existing MATCH, it may never take effect even if the syntax is valid. After saving, inspect the final runtime rules, not just the text in the editor. Preserve proxy group names exactly, including spaces, punctuation, and non-English characters; don’t shorten them from memory. If a target name is missing, fix the reference first.

Add one easy-to-verify rule at a time, reload the configuration, make a new connection, and check whether its details show the new match. If an old connection is still open, close it or restart the app that made the request. If the rule still doesn’t match, check whether the connection shows a domain or IP, whether a broader rule comes first, whether the app bypasses the core, and whether the override actually reached the runtime configuration. This makes it possible to isolate the issue instead of guessing after adding a whole rule set at once.

07 TUN Mode: Expanding Traffic Capture and Coordinating DNS

When to use TUN

If your browser routes correctly but an app ignores the system proxy, first check whether the app supports its own HTTP or SOCKS proxy settings. Consider TUN only when there is no suitable proxy setting and you genuinely need to capture more network requests. TUN routes traffic to the core through a virtual network interface, affecting more of the operating system than a system proxy does. Enable it only after the basic connection works.

Before enabling TUN, note the current system proxy, DNS settings, and status of other VPN tools, and make sure you know how to restore the setup afterward. Close other tools that may compete for the default route, and install the service or grant permissions required by the client. Don’t enable multiple virtual interfaces at once and then try to work out which one caused the issue. Mobile VPN interfaces and desktop TUN controls work differently; don’t apply desktop YAML as a replacement for all phone settings.

Understand the interface, routes, and DNS together

TUN capturing traffic does not automatically make DNS resolution work correctly. Apps may resolve addresses through the system DNS, encrypted DNS, or their own resolver; the core may also handle some DNS requests. If domain information does not follow the expected path, domain rules may behave differently than they do in system proxy mode. If a direct IP works but a domain does not, check DNS first instead of immediately replacing every exit or changing every rule.

# Mihomo field example; whether these are needed depends on how the client manages TUN
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

This configuration illustrates fields for automatic routing, exit interface detection, and DNS interception; it is not a complete, standalone configuration. A graphical client may generate these fields itself, so manage them through its settings where possible and avoid duplicate overrides. any:53 does not automatically handle every type of encrypted DNS. A DNS request sent over HTTPS by an app is not the same as a traditional query on port 53. Actual behavior also depends on DNS settings and route scope.

Understand Fake-IP and real address resolution

Fake-IP assigns an internal mapped address to a domain and lets the core associate the address with that domain; it does not move the destination server to that address. As a result, a system tool may show an address that is not the site’s real public IP. One lookup alone is not enough to conclude that traffic was incorrectly intercepted. Some apps depend on real addresses or special discovery mechanisms and may need specific domains excluded. Keep exclusions narrow instead of disabling DNS handling altogether.

After changing DNS behavior, the system or apps may still have old results cached. Close relevant connections, resolve the domain again, and check the logs; if necessary, flush the DNS cache using your OS documentation. If LAN printing, shared folders, or device discovery stop working, check private-range routing, local domain resolution, and exclusions. Don’t assume every LAN issue is a node failure or open the listener to all interfaces to fix a DNS problem.

Test the browser, affected app, and LAN resources separately, and watch the connections page to see whether they reach the core. If one app fails, check its protocol and proxy support; if every app fails, focus on the traffic capture path. After exiting the client, verify that system networking has returned to normal. Enable auto-start and automatic traffic capture only after these checks pass. A webpage loading briefly is not enough to prove the setup is stable.

08 Routine Maintenance: Updates, Backups, and Layered Troubleshooting

Handle the three types of updates separately

Client, core, and subscription updates change different things. A client update affects the interface and system integration; a core update may change protocol, rule, and DNS behavior; a subscription update mainly changes provider-supplied nodes and rules. Don’t update all three before testing, or it will be hard to tell what caused a change. Update them individually as needed and note the mode, configuration name, and key settings before and after each update.

Save a recoverable configuration before updating, and read the release notes relevant to your setup. Subscription fields may require a newer core, while an older client may not manage new core features correctly. If a compatibility error occurs, check the client and core combination before considering a rollback. Don’t mix unknown files from multiple sources. When restoring a backup, confirm the configuration format your client recognizes rather than overwriting all of its internal data.

What to keep in a backup

A useful backup should include at least the subscription source, persistent overrides, custom rules, proxy group selections, and key port, TUN, and DNS settings. A subscription cache can help with temporary recovery, but it does not replace the subscription source or custom settings. Screenshots can remind you which switches were enabled, but they cannot restore long rules. Export the configuration as text and add a short note about your setup; this is usually easier to migrate than saving only the app directory.

A backup may contain credentials for accessing a service, so store it somewhere access-controlled and avoid sharing it publicly when transferring between devices. A computer and phone can use the same subscription link, but their ports, interfaces, cache paths, and TUN settings may differ. For multi-device sync, share the service and rule intent first, then configure system-specific settings on each device. See Ways to Share a Subscription Between a Computer and Phone for details.

Troubleshoot by changing one variable at a time

First check whether the basic network works without the proxy. Then check that the core is running and the port is listening, inspect the rule matched by the target request, and finally check the remote connection. Record what each step reveals. Temporarily switching to global mode can isolate rule-related issues; it is not a universal fix. Temporarily disabling TUN can help isolate traffic capture issues; it does not mean TUN must stay off permanently. Restore the original settings when troubleshooting is done, then test again.

Use the log level needed for the current issue. If you need more detail, raise it briefly, reproduce the problem once, save the relevant lines, then restore your usual setting to avoid keeping extensive access logs. When asking for help, include the OS, client, current mode, traffic capture method, and full symptoms, along with relevant logs after redacting sensitive details. Don’t upload your entire subscription or bundle unrelated browsing history.

Latency tests are one useful data point, not a promise of overall performance. The test address, handshake, destination site, and bandwidth needs all affect results. If a test looks good but an app remains slow, inspect that app’s actual connections instead of running the test again and again. See Why url-test Latency Can Differ from Real-World Performance to avoid treating one number as a measure of an entire exit.

09 Advanced Setup: Proxy Groups, Rule Sets, and Recoverable Configurations

Refine your policy structure before adding automation

Once the basic connection is stable, the goal of advanced configuration is not to make it longer but to make choices, updates, and rollbacks easier to understand. First set clear policy boundaries for everyday use, specific services, and direct-connection exceptions; consider automation afterward. A clearly named proxy group with fewer layers is easier to explain than several groups that reference one another. Before creating a group, write down what it should do and which exit to fall back to if something goes wrong.

A select proxy group lets you choose manually, making it suitable when you need a fixed exit. url-test selects from candidates based on tests to a specified address; fallback switches according to candidate order and availability. These groups use different selection logic—they do not all mean “automatically pick the fastest.” Test requests also use network resources, so set an appropriate check interval instead of testing frequently just to see the interface change.

# Configuration snippet: matching nodes must already exist under proxies
proxy-groups:
  - name: Everyday choice
    type: select
    proxies:
      - Automatic selection
      - DIRECT

  - name: Automatic selection
    type: url-test
    proxies:
      - Exit A
      - Exit B
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

“Exit A” and “Exit B” are example reference names; replace them with node names that already exist in your configuration. Choose a test address that is reachable in your environment and suitable for regular checks. interval sets the check interval; tolerance helps reduce unnecessary switching due to small fluctuations. Neither parameter guarantees speed. For apps that need stable sessions, consider how switching exits may affect sign-ins and long-lived connections.

Manage rule sets as separate dependencies

When adding a rule provider, record its source, behavior type, update method, and where it is referenced. Changes to remote rules can change routing, so an unchanged configuration file does not guarantee unchanged behavior. Keep high-priority custom exceptions as rules that run first, and periodically check that rule sets still update. If a download fails, check the provider status; a working proxy group does not prove that every external dependency loaded.

Have a specific reason before adding DNS or sniffing features. Sniffing attempts to extract domain names and other details from certain protocol traffic; its capabilities are limited by the protocol and encryption, and it cannot recover a domain for every connection. If your current rules work reliably, there’s no need to enable every option just to complete a feature list. For each new feature, record which requests it handles, its limitations, and how to restore the previous behavior.

Use a repeatable configuration change process

Make changes in four steps: copy the working configuration, make one small edit, validate the syntax and runtime behavior, then record the result before keeping it. If you run a standalone Mihomo core and the executable is available in your terminal, use the command below to check the configuration. Users of graphical clients can start with the built-in configuration checker. Passing a syntax check only means the configuration was accepted; you still need to verify the rules and exit with a real connection.

mihomo -t -f config.yaml

For advanced practice, try these steps in order: add a direct-connection exception for one domain, create a separate policy for a service, verify that a rule set updates, then build a recoverable backup. After each step, check that the runtime rules and connection chain match your expectations. When choosing an exit, compare latency, pricing multipliers, region, and protocol, but don’t rely on a single test instead of observing performance over time.