Clash User Guide
From Beginner to Advanced

1. Core Concepts: Client, Core, and Traffic Entry Points

The client handles controls; the core handles traffic

The Clash ecosystem is not a single installer that does everything. A graphical client provides subscription imports, settings, proxy group selection, and logs. The core reads the configuration and handles DNS resolution, rule matching, and connection forwarding. mihomo is a commonly used core in this ecosystem. Even when two clients use similar cores, they may differ in overrides, system integration, and where configurations are stored. The same-looking button does not guarantee identical behavior.

The configuration file defines how the client and core work together, usually in YAML. It may contain proxy nodes, proxy groups, routing rules, listening ports, and DNS settings. A subscription is one way to obtain this information: some URLs return a complete configuration, while others provide only a list of nodes. A successful import means the client accepted the input; it does not prove that the rules are correct, the outbound connection works, or every app is using the proxy. Check each separately.

Understand a connection by asking three questions

When troubleshooting access, ask whether traffic reached the core, which rule matched, and whether the selected outbound can connect. The system proxy provides an HTTP or SOCKS entry point for apps that follow system settings; apps with manual proxy settings can connect directly to a local listening port. TUN uses a virtual network interface to capture traffic that matches its routing rules. Each entry point covers different traffic and requires different troubleshooting, so a working browser does not prove that every app works.

Once traffic reaches the core, rules are generally checked from top to bottom. The first match passes traffic to a policy, which may be a direct connection or a proxy group. The group then selects a node, which connects to the remote proxy service. In other words, “rule mode” is not a proxy protocol, and “system proxy” is not a proxy group. Confusing these layers can lead to endless node switching without fixing the actual entry-point problem.

Understand the limits before configuring

The client itself is not a working remote proxy service. Node addresses, ports, credentials, and availability depend on the configuration source; an expired subscription, invalid credentials, or service restrictions usually cannot be fixed by enabling TUN. A proxy also cannot fix the destination website's login restrictions or service outages. Test services you are authorized to access, and follow local laws, network policies, and terms of service. Do not mistake a service-side rejection for a client issue.

Before you begin, note your operating system, client, configuration source, current traffic entry point, and which apps you want to cover. Never save subscription credentials in a public note. First get browser access working, then add other apps, and only then consider capturing all traffic. Change one thing at a time so you can return to the last working setup if something breaks. For more on how the core and graphical clients fit together, see the Clash ecosystem overview.

2. Choosing a Client: Match Your Platform First

For your first setup, stick to one consistent workflow

This release page recommends Clash Plus on supported platforms. It suits users who want to learn subscription, policy, and connection management within one product. Choose based on your device and required features: desktop users may care more about service mode, rule overrides, and window management; mobile users may prioritize VPN permissions, background operation, and battery use. List what you need to solve before comparing clients. That is usually more effective than installing several at once.

The Windows downloads also include Clash Verge Rev, FlClash, Clash Nyanpasu, and the discontinued Clash for Windows. macOS downloads include Clash Plus, Clash Verge Rev, FlClash, and the discontinued ClashX Meta. Archived clients may be useful for older environments or migration, but matching screenshots in an old tutorial are not a good reason to choose one for a new installation. Before migrating, back up your subscription source and custom rules, then set up system integration again in the new client.

Platform limitations matter more than the interface

On Android, choose between Clash Plus, Clash Meta for Android, FlClash, and Surfboard based on configuration compatibility. Surfboard uses a different configuration system from Clash YAML, so you cannot treat any full YAML file as a universal import. The iOS downloads list a store link for Clash Plus and its official website, clashplus.io. Mobile platforms generally use the system VPN feature to establish a tunnel; do not follow desktop instructions for setting a system proxy port.

On Linux, graphical options include Clash Verge Rev and FlClash. Users setting up a server, router, or self-managed service can also consider the standalone mihomo core. A standalone core requires you to manage startup arguments, working directories, permissions, logs, and services; it does not include a graphical client's subscription controls. For everyday desktop use, start with a graphical client and get a working configuration before learning core deployment. That means fewer variables to manage at once.

Configuration compatibility does not mean every extension is supported

When comparing clients, check node protocols, rule syntax, and client extensions separately. A field recognized by one core may be rejected by another; a graphical client's scripts or override formats may not be part of the standard configuration. If a tutorial asks you to add a field, first check which product and core it targets. Do not delete an entire DNS or proxy group section just to silence an error: the file might load, but its routing behavior could change.

Keep just one client in charge of system-wide traffic capture. You can use other products for comparison, but before testing, quit the old client, turn off its system proxy, and check that its background service has stopped to avoid port or route conflicts. Find installers and architecture details on the client downloads page. If you are moving from an older client, read the migration guide for discontinued clients to learn what can carry over and what to set up again.

3. Installation and Initial Checks: Set Up a Recoverable Environment

Check your architecture and existing setup

Check your system information before downloading; your computer's brand does not tell you its processor architecture. On macOS, distinguish Apple Silicon from Intel. On Android, choose a package that matches the device's supported instruction set. On Linux, account for both architecture and distribution package format. A downloadable installer may still be wrong for your device. If it will not run, has an unsupported format, or has the wrong architecture, check your system information before trying the same file again.

Before installing, note your current system proxy settings, any active VPNs, and your organization's network requirements. If you have used another proxy client, turn off its traffic capture in the interface and quit it normally; check for a background service if needed. Do not delete an old configuration directory before you know what it contains—it may hold custom rules and subscription sources. A safer approach is to keep a private backup and create a separate configuration for the new client.

Grant permissions only when needed

On Windows, a regular system proxy and TUN, which may require elevated permissions, are different things. Service mode typically delegates privileged operations to a background service; the exact controls depend on the client. Before installing a service, make sure the permission prompt belongs to the product you are using. You do not need to run the entire interface as administrator just to connect a browser. If your organization restricts the installation directory, ask your device administrator rather than disabling security controls.

The first launch on macOS may prompt you to approve the app and a network extension. Android and iOS typically ask you to confirm a system VPN configuration. After granting permission, return to the client and check that it actually shows a connected state. Linux graphical clients may also depend on desktop components or system service permissions. If you see a missing dependency or permission error, keep the full error text and follow the instructions for your distribution and client. Not every startup issue is a subscription problem.

Check the basics on first launch

Find the configuration, proxy groups, connections, and logs pages before importing a subscription. Use the port shown in your client settings. 7897 in this guide is only an example, not a universal default. If a port is already in use, identify the process and decide whether to stop the old service or change the new port. If you change it, update any apps with manually configured proxy settings so they do not keep connecting to the old address.

For an initial check, use a local terminal to see whether command-line tools are affected by old proxy environment variables. How you check depends on the terminal. The commands below only read variables visible to the current process; they do not change the system. If you find proxy variables, determine whether they come from the current terminal session, a user profile, or a development tool. Turning off the graphical proxy switch does not necessarily clear them.

# Linux / macOS: Show common proxy environment variables
env | grep -iE '^(http|https|all|no)_proxy='

# Windows PowerShell: Show proxy environment variables for the current process
Get-ChildItem Env: | Where-Object Name -Match '^(HTTP|HTTPS|ALL|NO)_PROXY$'

Installation is complete when the client does more than open: the configuration loads, listening ports do not conflict, traffic capture can be turned off, and logs are accessible. Check these basics first so you have a reliable baseline for troubleshooting. For Windows service permissions and startup settings, see the Clash Verge Rev installation guide. Do not assume other clients use menus with the same names.

4. Subscriptions and Configuration: Separate Remote Sources from Local Changes

Start by identifying the input

A subscription URL may return a complete Clash configuration, a list of nodes, an encoded list of links, or a format for another product. Before importing, check the provider's format instructions and use an entry explicitly marked for your client. Create a remote configuration in the client's subscription or configuration page, paste the URL, and download it. Then check what loaded. If you see a parse error, first find out whether the response is actually a configuration instead of repeatedly refreshing the nodes.

Subscription URLs often contain account-identifying parameters and should be treated like credentials. Before sharing screenshots, asking public questions, or copying logs, redact the full URL and any authentication fields. Do not send a private subscription to an unfamiliar data-processing service just to convert its format. In examples, https://example.com/sub?token=xxxx shows the shape of a URL, but contains no real subscription and cannot connect. Get real URLs only from authorized sources.

What to check after importing

When the download finishes, switch to the new configuration and confirm it is the active one. Then check that proxy groups are present, each group has an available outbound, and rules refer to valid policies. In some clients, “subscription updated” only means the file was saved; the core may still reject it when reloading due to syntax or reference errors. Use the active configuration indicator and logs to confirm what is actually running—not just the success message beside the update button.

YAML is sensitive to indentation and structure. Use spaces, not a mix of spaces and tabs. List items usually start with a hyphen, and indentation should be consistent at the same level. Quote strings that contain special characters. An error may point to the line after the actual problem, so check the surrounding structure too. The example below shows structure only: it includes no proxy nodes and is not a complete replacement for a subscription. Keep the valid nodes and policies from your source.

# Structure example: merge with your actual subscription
mixed-port: 7897
allow-lan: false
mode: rule
log-level: info

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

Keep subscription updates separate from personal settings

Editing a remote subscription directly is risky because the next update can overwrite your changes. For rules, DNS settings, or port changes you need to keep, use a client-supported override, merged configuration, or separate rules file, and learn how it is applied. Some products merge settings before generating the final configuration; others modify the configuration object with scripts. These mechanisms are not interchangeable. After making changes, inspect the effective configuration and check that a same-named subscription field has not overwritten yours.

When an update fails, troubleshoot network access, response content, and configuration parsing separately. A timeout or certificate error usually occurs while fetching. If the download works but YAML parsing fails, check whether the response is actually a login page, expiration notice, or error message. If nodes are present but connections fail, investigate authentication and outbound access. If you already have a working configuration, keep it. Do not delete the local cache while the source is unavailable, or you could lose your last working setup.

Subscription conversion helps adapt formats; it will not revive failed nodes or guarantee that every field maps correctly. After converting, check proxy group names, rule order, and DNS settings so you do not end up with nodes but lose the policies that use them. For a reliable result, reload once and test real access. To follow a simpler setup, return to the subscription import guide. For common failure causes, continue with Frequently Asked Questions.

5. Proxy Modes and Testing: Find the Path Your Traffic Takes

Rule, Global, and Direct modes change policies

Rule mode selects an outbound according to the configuration's rules, making it useful for everyday setups that need access to both local services and remote resources. Global mode typically sends connections entering the core through the global policy, which makes it useful for temporarily testing an outbound. Direct mode connects to destinations without a proxy. None of these modes automatically sends every app into the core. If an app bypasses the client, that is an entry-point issue—even with Clash set to Global mode.

For your first test, use just one main entry point. On desktop, start with the system proxy, select Rule mode, and choose a specific outbound in a commonly used proxy group. On mobile, first connect through the system VPN. Open a known accessible test site and check the connection list for its domain, matched rule, and final policy. If the page loads but there is no corresponding connection entry, consider browser caching, connection reuse, or whether the app used the expected entry point.

Use comparison tests to narrow down the cause

Browsers and terminals do not necessarily use the same proxy settings. A command-line request can explicitly use the local HTTP proxy, bypassing differences in environment variables and testing whether the listening entry point works. The example assumes the mixed port is 7897; replace it with the port in your settings. It requests a public example domain and only tests that request's path. It cannot prove that every site, protocol, or app is working.

# Explicitly use the local HTTP proxy
curl -I --proxy http://127.0.0.1:7897 https://example.com

# Bypass the proxy for comparison
curl -I --noproxy "*" https://example.com

If the first command cannot connect to the local port, check whether the client is running, the port is correct, and the listener is active. If it reaches the local client but the remote request fails, check the selected node, rules, and logs. If direct access works but proxy access fails, compare with another known working outbound. If both fail, consider the destination service, current network, and system clock too. Do not change the node, DNS, entry point, and rules all in one test; you will not know which change mattered.

Understand proxy groups and connection reuse

A manual group is useful when you need a fixed outbound. An automatic testing group selects an option based on the configuration's probe settings, while a failover group switches when the current option is unavailable. Probe addresses, intervals, and tolerance affect selection, and a successful probe does not mean every service is reachable. Early in troubleshooting, temporarily pin a single outbound to reduce interference from automatic switching. Restore the automatic policy once the path is clear.

Existing long-lived connections may not move immediately when you switch modes or nodes. Browser connection pools, downloads, and messaging apps may keep using an old connection. To test a new policy, make a fresh request; if needed, close the relevant connection in the client or restart the app. You do not need to restart the whole device every time. Connection start times and final outbounds are more useful indicators of an app's actual path than the currently selected proxy group alone.

Also distinguish successful access from privacy goals. Routing a connection through a proxy does not mean DNS, app telemetry, and account activity have the same privacy boundaries. Browser secure DNS, app-specific resolution, and UDP traffic may need separate checks. If a store app ignores the expected proxy, see the Windows UWP loopback exemption guide. First identify the app type and its restrictions, then decide whether to use a loopback exemption or change the entry point.

6. Routing Rules: Make Traffic Intent Clear and Testable

Put exceptions before general rules

Routing rules are generally checked from top to bottom, and the first match determines the policy. The order is part of the configuration logic. A common structure is to handle specific service exceptions first, then address ranges such as the local network, followed by broader rule sets and a final fallback. Do not put broad direct or proxy rules ahead of all specific rules. Later entries could be syntactically correct but never get matched.

Domain rules express service intent; address rules express network ranges. DOMAIN matches an exact domain. DOMAIN-SUFFIX covers the specified domain and its subdomains. IP-CIDR matches an address range. GEOIP uses geographic IP data. MATCH is the final fallback. Suffix matching is not an arbitrary substring search. Use real domain boundaries, and do not put paths, protocol prefixes, or query parameters in a domain field.

Check policy names before rule syntax

The last rule must point to a policy that actually exists. PROXY is an example proxy group name; confirm that your configuration has a group with that exact name or replace it with a valid one. DIRECT is the built-in direct policy. This example shows a specific-to-fallback order, not a complete rule list for every setup. Existing subscriptions may include more detailed service rules; preserve any necessary logic when merging.

rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

no-resolve avoids triggering an extra DNS lookup to match certain address rules against a domain. It does not disable DNS entirely. This can reduce unnecessary lookups, but the rule can only work as intended when the destination address and other required information are already available. Geographic IP data is not definitive proof of where a service operates: CDNs, cross-region services, and changes in IP allocation can all make GeoIP-only policies a poor fit for actual traffic.

Rule sets and local overrides have different roles

As rule lists grow, rule providers can maintain collections that you reference with RULE-SET. A provider typically specifies the rule behavior, how to fetch the data, where to store it, and how often to update it. The collection must match its declared behavior. A domain collection cannot be used as arbitrary rule text. Learn a few manually written rules before adding collections. Otherwise, when traffic is routed incorrectly, it is hard to tell whether the problem is a reference, a failed download, or the collection itself.

After adding a rule, check its position in the effective configuration, then visit the target and inspect the connection details. If it does not match, check the actual domain, whether an earlier rule took precedence, whether the app provided only an IP address, and whether an old connection is still being reused. Websites often depend on multiple domains. If the homepage uses a proxy but the login API connects directly, the service may still fail. Add only the scope needed for the actual connections instead of routing all traffic through the same policy.

For long-term maintenance, document why each custom rule exists and save it separately from subscription content. An old exception can keep a service on the wrong route, so review exceptions after a service recovers or a rule set updates. Treat Clash GeoIP updates as routine data maintenance, not a universal fix for every outage. Look up unfamiliar terms in the glossary. Every rule should answer: why is it here, what should it match, and where should the traffic go?

7. TUN and DNS: Understand Resolution Before Capturing More Traffic

TUN addresses traffic entry, not outbound configuration

TUN uses a virtual network interface and routes to pass connections to the core. It is useful for apps that ignore the system proxy and for handling more types of traffic in one place. It depends on system permissions, the network stack, and the client implementation; platforms do not all use the same controls or parameters. Before enabling it on desktop, confirm that the system proxy path works and pause other VPN tools that modify routes. Avoid adding another layer of possible failure before verifying a basic outbound.

After enabling TUN, check in order that the virtual interface is up, target traffic appears in the connection list, rules match, and local network resources remain accessible. A company VPN, container network, or virtual machine may have address ranges that conflict with automatic routing. Define exclusions based on the network or choose another entry point; do not keep switching network stacks at random. Be especially careful when managing a device remotely, because route changes can disconnect your current session.

DNS turns domain names into connection destinations

Apps may use system DNS, a browser's secure DNS, or their own built-in resolver. A client's DNS settings only affect queries that enter its processing path. Setting a DNS server does not mean every query uses it. When troubleshooting Clash DNS leaks, first decide which queries should take which path, then verify that using client logs and system settings. One website test cannot establish how the entire device behaves.

Fake-IP assigns a domain an address from a reserved range. The core keeps the mapping between the domain and the connection to support later routing decisions. These are not the destination server's real addresses, so seeing them does not necessarily mean DNS is broken. Some local-network discovery, device-control, or real-IP validation apps may not work well with this mechanism. Add targeted exclusions or use another DNS mode as needed; do not disable DNS handling across the board without understanding the impact.

# mihomo partial example: confirm listening ports and platform support first
dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.alidns.com/dns-query

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

Merge this configuration into a valid mihomo configuration; it is not suitable for every graphical client, and some clients may regenerate these fields through their interface. Listening for DNS on a local port does not automatically change the system's DNS settings. TUN DNS capture also cannot capture encrypted DNS connections that an app establishes on its own. The upstream shown is optional and is not guaranteed to suit every network. Consider reachability, trust, and local network requirements before using it.

Roll back according to the scope of the failure

If all access fails after enabling TUN, turn it off and restore the previously tested entry point. Check whether basic connectivity returns, then inspect permissions, routes, and DNS logs. If only internal domains fail, check the internal resolver, search domains, and routes instead of immediately switching remote nodes. If just one app has a problem, compare system DNS, the app's resolver, and Fake-IP exclusions to find the difference. On mobile, also account for background operation; see the Android battery and background operation guide.

8. Ongoing Maintenance: Updates, Backups, and Troubleshooting Notes

Know which of the four things you are updating

Client updates, core updates, subscription updates, and rule-data updates are different operations. A client update affects the interface and system integration; a core update may change protocol support or field behavior; a subscription update changes nodes and source configuration; GeoIP, GeoSite, and rule-set updates affect matching results. When something changes, first identify which update occurred instead of blaming every issue on a software upgrade. Maintenance notes can be simple, but should make the main before-and-after changes clear.

If your setup is stable, do not update every component and rewrite DNS at the same time. Back up first, make one change at a time, and test common tasks after each change. If a desktop client lets you switch cores independently, read the compatibility notes instead of replacing the executable based on its filename alone. Keeping a working configuration is more important than keeping piles of installers from unknown sources. When rolling back, consider configuration syntax too: an older core may not understand newer fields.

Back up the intent, not just the files

A useful backup includes subscription sources, custom rules, overrides, proxy group selections, and any necessary system integration notes. A configuration exported by the client may contain node passwords and subscription credentials, so restrict access and never commit it to a public code repository. System proxy settings, startup behavior, and service installation status may not be included in the export. After moving to another device, you may still need to grant permissions and check ports. Having a backup file does not prove that you can restore it.

When it will not disrupt everyday use, test a restore: create a temporary configuration, import the backup, check policy references and rule order, then return to the original. To migrate between clients, restore the portable YAML content first, then recreate overrides and system settings using the new product's approach. Do not overwrite the new client's entire data directory. Old caches, databases, and client-specific fields may be incompatible. Keep the original backup until you have tested all your common use cases in the new setup.

Troubleshooting notes should describe one specific failure

When something breaks, note when it happened, which app and domain were involved, the current entry point, and the selected policy, then reproduce it once. If you temporarily increase log verbosity, watch disk usage and sensitive information exposure; restore an appropriate level when done. When sharing feedback, include only necessary error context and redact subscriptions, credentials, and personal paths. Keep the error type intact: trimming everything down to “connection failed” removes useful diagnostic information.

Verify Clash startup behavior separately: after a reboot, check that the client starts, the background service is available, the configuration loads, and traffic capture works as expected. Some apps start after login; some services run before the desktop. They cannot be judged by the same criteria. Automatic subscription updates also depend on initial network access. If downloading the subscription requires a proxy path that is not yet working, keep a valid local configuration to avoid a startup loop between fetching the configuration and establishing a connection.

After resolving an issue, undo temporary Global mode, verbose logging, and overly broad exception rules. Note the cause and what fixed it; do not leave emergency settings in place permanently. For recurring problems, look up the relevant topic in Frequently Asked Questions, under basics, installation and configuration, usage tips, or troubleshooting. If you need more help, share steps to reproduce the issue and a redacted configuration excerpt—a screenshot of the failure alone is less useful.

9. Advanced Topics: From a Working Setup to a Maintainable One

Work toward testable outcomes, not more switches

After the first eight chapters, the goal is not to enable every feature. It is to make your configuration understandable, portable, and reversible. Start with one clear objective: route a work service through a specific policy, give a group of devices a separate outbound, or turn repeated rules into a collection. Define how you will verify the result, then choose the fields you need. If your existing rules already work, adding sniffing, scripts, and complex proxy group chains can raise maintenance costs and make troubleshooting harder.

To start, divide the configuration into five sections: basic listeners, DNS, node sources, proxy groups, and rules. Note who maintains each section. Remote subscriptions provide nodes, local overrides handle personal requirements, and rule providers manage reusable collections. This division is easier to understand than one huge file. If the client generates its configuration, learn the difference between its input and final files. The final file can help you inspect the result, but may not be the right place for ongoing edits.

Run static checks before testing real traffic

When running mihomo standalone, first test the configuration for syntax and reference issues, then start actual traffic capture. The command below assumes the executable is on your command path and the configuration to test is in the current directory. Passing the test only means the core accepts the file; it does not prove that node credentials work, upstream DNS is reachable, or routes meet your needs. If a graphical client supports configuration validation, use its supported workflow rather than manipulating its internal working directory.

# Standalone mihomo: Check the current configuration
mihomo -t -f ./config.yaml

# Standalone mihomo: Run with a specified configuration file
mihomo -f ./config.yaml

Next, create a small regression checklist: one direct destination, one proxied destination, one local network service, and any UDP or long-lived connections you actually need. After each change, check the entry point, rule, and outbound separately and record whether they behave as expected. Choose test destinations based on your own environment; a public probe address does not tell you how your services will perform. For login, payment, or region-sensitive services, also consider account security checks and session invalidation caused by changing outbounds.

Automation and remote management require tighter controls

Before using a control API or dashboard, check its listening address and authentication. If you only need local management, bind it to the loopback address. Do not expose the management port on every network interface just to access the dashboard from a phone. If you genuinely need LAN access, add access controls and firewall rules, and remember that a proxy listener and a control interface are separate services. Allowing LAN connections does not authorize every device to use them; limit exposure to what you actually need.

Server and router deployments also require a working knowledge of service lifecycles: which user runs the service, where it reads data, whether it recovers after a reboot, how logs are rotated, and what happens after an unexpected exit. Design a separate rollback plan for transparent proxying, firewall forwarding, and policy routing. Do not experiment with unfamiliar routes on a remote device you depend on. Test in an environment you can access locally before moving the setup to a device expected to run continuously; this reduces the risk of losing access.

For ongoing learning, prioritize the current configuration guides for your core and client, especially their configuration layers, default behavior, and compatibility limits. Older articles can explain the concepts, but cannot replace inspecting the active configuration. To review the basics, trace the traffic path again from the core concepts in this guide. To rebuild your setup, return to the quick-start guide. A configuration is maintainable when you can explain what each setting does, how to verify it, and how to undo it—not merely when it works for now.