The Complete Guide to Clash Clients and Subscription Setup

1. Core Concepts: Clients, Cores and Configuration

How a Request Flows

The Clash ecosystem is not a single application with a consistent interface. A client provides controls for importing configurations, selecting modes, changing system settings and viewing logs. The core handles connections, evaluates rules and establishes outbound connections. They are usually bundled together, but may not update on the same schedule. To confirm whether a feature is supported, check both the interface and whether the running core recognizes the relevant fields. The client’s name alone is not enough.

Think of a request as a path through the app, connection method, core, rules and outbound. An app may connect directly to a local proxy port or hand off requests through the system proxy. With TUN enabled, a virtual network interface may capture traffic instead. The core then uses the selected mode and rules to send the request direct, reject it or pass it to a proxy group. Understanding this path helps pinpoint whether a failed page is caused by app traffic not reaching the core, DNS resolution or the remote connection.

A Subscription Is Not a Complete Configuration

A subscription URL points to a remote resource; it does not enable a connection by itself. The response may be a complete configuration or just a resource file for use with a proxy provider. A complete configuration usually includes proxies, proxy groups, rules and DNS settings, while a resource file covers only part of that setup. Importing a node list as a complete configuration can cause a parsing error—or leave you with resources but no usable proxy group. Before importing, check the format provided and what your client expects.

YAML is commonly used to represent configuration hierarchies, and indentation matters. Root-level and nested fields are not interchangeable; list items usually start with a hyphen, and indentation should use spaces, not tabs. Duplicate fields may be handled differently by different parsers, so merge them intentionally rather than assuming the later entry overrides the earlier one. A file that parses can still have broken proxy-group references, resource paths or permissions. Passing syntax checks is only the first step.

Configuration Sources and Runtime State

Treat the original subscription, override files and final active configuration as separate things. A remote subscription may be downloaded again during an update; overrides preserve local changes such as ports, rules or DNS settings; and the final configuration is what the client produces after merging everything for the core. If settings revert, fields have no effect or rule order changes, inspect the final configuration instead of repeatedly editing a temporary downloaded file. Clients merge arrays differently, so do not assume every override appends to the existing list.

Also distinguish between “configuration saved,” “core loaded” and “the target app is using the proxy.” Saving in an editor does not mean the core accepted the changes. A successful core reload does not mean a browser or other app connected to it. Check the load result and connection log, then make a new request from the app you are testing. Existing connections may keep using the old outbound, so an open tab or session can make a working change look ineffective.

2. Choosing a Client: Platforms, Cores and Maintenance

Start with Your Platform and Use Case

Choose a client based on your operating system, then check your processor architecture and use case. For everyday desktop or phone use, start with a graphical client; consider running the core directly only on servers or routers. The download page lists Clash Plus first on supported platforms. If you need desktop configuration management or mihomo features, compare Clash Verge Rev and FlClash as well. The recommended order does not mean every client has identical features—check subscription formats, connection methods and platform permissions individually.

On Windows, check System settings for your system type, especially whether it is x64 or ARM64. On macOS, identify whether your Mac uses Intel or Apple silicon rather than choosing by operating system alone. On Android, choose a package that matches your device architecture; if you are unsure, check whether the download page offers a universal package. On Linux, you also need to consider your distribution’s package format and desktop environment. A successful installation does not guarantee identical tray behavior, service management or permission prompts.

Check Feature Compatibility, Not Just the Name

Clash, Clash Meta and mihomo are related, but they are not interchangeable names for software that always supports the same fields. Protocols, rule types and DNS options vary by core implementation, and online configurations may target different branches. Before switching clients, note which features you currently rely on and verify each one in the new client. Pay particular attention to proxy providers, rule providers, script-related features and platform-specific connection methods. Do not migrate every setting from an old configuration at once.

Check configuration formats carefully on mobile. Surfboard uses a different configuration system from Clash YAML, so a file that works with one proxy client may not import into another. For iOS, use the download page to open the Clash Plus App Store listing, and check the product details at clashplus.io. Use the import options available in the app itself; desktop fields do not necessarily map to mobile settings.

Legacy Clients and Migration Costs

Clash for Windows and ClashX Meta remain on the download page as discontinued legacy options. They may be useful for older environments or consulting existing configurations, but old tutorial screenshots should not be your only guide to a new installation. When choosing a maintained client, check where it stores configurations, how to export logs and what happens to system settings when you uninstall it. A clear backup and recovery path matters more than the number of buttons, especially when moving between devices or maintaining a setup long term.

Do not install multiple clients and run them on top of one another. They may compete for the same port, system proxy or VPN tunnel, making the results hard to interpret. Compare clients by testing the same configuration, network and app, and exit the previous client before each test. Record what works before deciding which client to keep. Find platform installers and links on the client downloads page. For more on the core relationship, see Clash, Clash Meta and mihomo: Key Differences.

3. Installation and Checks: Permissions, Ports and First Launch

Keep a Way to Roll Back Before Installing

Before installing, quit any other proxy clients and note your current system proxy settings. If the device is on a corporate or campus network, or uses a dedicated VPN, check its administration requirements first to avoid interrupting work connections. On devices that have used an older client, check for background processes and startup items; closing a window may not stop the core. For the first installation, use a standard location you can manage, rather than adding complex directory permissions or synced configuration folders.

On Windows, complete the installer and leave TUN off for the first launch. Confirm that the main window, configuration page and log page open normally. If Windows displays a security warning, verify the download source and release notes instead of disabling security features. Write access to the installation directory is separate from write access to the data directory. If the client starts but cannot save settings, check data-directory permissions, available disk space and whether sync or security software has locked a file.

On macOS, install the current package as directed and grant the permissions requested by the system. If you move the app, old startup items or background services may still point to its previous location, so choose its final location before enabling automatic startup. On Linux, use the package method suited to your distribution. When dependencies fail, read the package manager output to distinguish missing dependencies, architecture mismatches and desktop environment issues. Do not assume every launch failure is caused by the subscription.

Mobile Permissions and Background Limits

On Android, you may need to grant VPN connection permission before or after importing a configuration. This lets the system establish a traffic-routing tunnel; it is not subscription authentication. You still need to start the connection in the client. If it drops when the screen locks, check battery optimization, background activity and the device maker’s auto-start settings, granting only the permissions the feature needs. iOS also requires permission for network configuration. Make sure another VPN app is not already using the connection tunnel.

Port Conflicts and Core Startup

Desktop clients commonly listen on local HTTP, SOCKS or mixed ports. A mixed port can accept both supported HTTP proxy and SOCKS connections, but programs will not necessarily use it automatically. 7890 is just an example port, not a fixed value across clients. If the log says an address is already in use, identify the process using it before deciding whether to stop the old program or change the port. If you change the client’s listening port, update the app’s proxy address too.

# Windows PowerShell: Check local listening ports
Get-NetTCPConnection -LocalPort 7890 -State Listen

# macOS: Find processes listening on TCP ports
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux: Check TCP listeners and processes
ss -lntp

An empty command result means no matching listener was found; it does not prove the client is broken. The port may be different, the core may not have loaded its configuration, or you may need elevated permissions to see process details. Confirm the actual port and runtime state in the client, then check the logs. If the process keeps exiting, start with configuration parsing errors, resource paths and permissions rather than reinstalling repeatedly. Reinstalling may leave the original data directory in place, so it may not change the conditions causing the problem.

4. Subscriptions and Updates: Importing, Resource Intervals and Overrides

Choose the Right Import Option

On the client’s configuration or subscription page, choose Add, Import or a similar option, then paste the full subscription URL into the address field. Check that chat apps have not wrapped the link onto multiple lines, that there are no extra spaces at either end and that all authentication parameters are present. After import, select the configuration you want to use. A new entry in the list only confirms that it was added; check the status and logs to verify it downloaded, parsed and loaded into the core.

Importing a local file may copy the YAML into the client’s managed directory or keep a reference to the original file; behavior varies by client. Changes to the downloaded original may not sync automatically. Some editor views, on the other hand, edit the managed copy directly. Confirm which file you are editing after import and keep a backup of the original. If the provider supplies an encoded node list or another format, use a compatible import option or a trusted conversion method. Changing the file extension alone will not work.

Updating a Full Configuration vs. Updating Resources

Updating a full subscription replaces the remote configuration content. Updating a proxy provider usually refreshes only that provider’s resources, while rule providers have their own download intervals. These may be controlled by separate options, so updating one does not guarantee the others are current. A subscription interval in the client interface may be in minutes, while mihomo’s provider interval field is typically in seconds. Do not copy an interface value straight into YAML or assume one field controls the update schedule for the entire configuration.

# Local proxy provider snippet: merge into the existing configuration
# The file must use the proxy provider format supported by the current core
proxy-providers:
  local-resources:
    type: file
    path: ./providers/local.yaml

proxy-groups:
  - name: Manual selection
    type: select
    use:
      - local-resources

The snippet shows how a provider and proxy group reference each other; it does not create a resource file. Before using it, create the file in the core’s actual working directory and confirm the client can access that path. An HTTP provider also needs a real resource URL, a file path and an update interval. Use an address from a trusted source, not a management webpage that is not intended as a resource endpoint. If the subscription returns HTML, a login page or an error message, it cannot be loaded as a YAML resource, even if the request itself succeeded.

Keep Local Changes in a Persistent Layer

Save custom ports, DNS settings and rules through the client’s supported override, merge or extension mechanism whenever possible. Direct edits to a remote file can be overwritten at the next update; manually copying the entire subscription means losing its remote update path. After setting an override, inspect the final active configuration to confirm the field hierarchy and array order. Rules need particular care: some mechanisms replace the entire list, while others insert rules at the beginning or end, with very different effects on fallback matching.

When an update fails, note which item failed and what kind of error occurred. For authentication errors, check the link and account status. For parsing errors, inspect the returned content and its format. For connection timeouts, distinguish local network issues, DNS resolution and the download path. A subscription that needs the current proxy to download, when that proxy itself depends on the subscription, can create a startup dependency. Restore a known working configuration on a trusted network before updating. Never paste a sensitive URL into a public conversion service or troubleshooting page.

5. Proxy Modes: Traffic Entry and Outbound Decisions

System Proxy Settings Are Not Proxy Modes

System proxy, TUN and rule mode operate at different layers. The system proxy tells apps that honor the setting to send connections to a local port. TUN provides another way to capture traffic. Rules, global mode and direct mode determine how the core handles connections it receives. So switching to global mode will not capture apps that are not using a proxy, and enabling the system proxy does not mean every request will use a remote proxy. Troubleshooting starts by checking whether the connection reached the core.

For everyday use, start with rule mode, which routes requests according to domains, addresses or other conditions. Global mode is useful for a quick test of a specific outbound, but you still need to select the right proxy group. Direct mode can help determine whether the remote route is causing a problem, but the comparison is meaningless if the app never connected to the core. When comparing modes, use the same app and destination, and start a new connection so network changes are not mistaken for mode differences.

Make a Reproducible Test Request

To test the system proxy, first check the client’s listening address and port, then see whether the app has its own proxy settings. Browser extensions, terminal environment variables and built-in proxy settings in developer tools can override the system default. Terminal commands do not usually use the same path just because the desktop system proxy is enabled, so test them with an explicit proxy argument. The command below sends a request to the local mixed port; change the port if yours is different. The destination is used for a simple HTTPS request.

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

A response confirms that this request used the specified port; it does not prove that traffic went through a remote proxy. The final outbound depends on the current mode and rules, so check the client’s connection page. If the command cannot connect to the local port, check the listener and process first. For certificate errors, check the system clock, certificate environment and destination site; do not make certificate verification bypass your regular fix. Interpret status codes in context rather than treating them all as proxy failures.

Mode Changes and Connection Lifetimes

Changing modes or proxy groups mainly affects new connections; existing long-lived connections may continue on their original route. Browser connection pools, messaging sessions and downloads are especially likely to keep old connections open. For a reliable test, make a new request in the app and, if needed, close the specific connection or restart that app rather than clearing the entire configuration. If the client can disconnect active connections, check the scope of that action so you do not interrupt an important transfer.

If webpages stop loading after you quit the client, the system proxy may still point to a local port that is no longer listening. Turn off any leftover proxy in system network settings, then check whether another program is changing it again. If you use proxy environment variables in a terminal, clear them from that session too. Once direct access is restored, restart the client and investigate its exit behavior. Switching between rule and global modes cannot fix an unreachable local port after the core has stopped.

6. Traffic Routing: Rule Order and Resource Management

Start with a Minimal Rule Set

In rule mode, rules are usually checked from top to bottom, and the first match determines where a request goes. A correct rule in the wrong position may never run. Put specific domains and higher-priority conditions before broader ones, and keep the fallback MATCH rule at the end. Before adding a rule, check the current match in the connection details to choose where it belongs. Appending rules without understanding their existing order often makes the file longer without changing the result.

Domain rules and address rules solve different problems. DOMAIN matches a specific domain; DOMAIN-SUFFIX covers that domain and its subdomains; and IP-CIDR matches an address range. If an app connects directly to an IP, or the domain is not passed to the core, the expected domain rule may not match. Check the destination details in the connection log instead of adding the same domain rule repeatedly. A rule can only match information that is actually available.

# Minimal rules example; does not include remote proxy resources
mode: rule
rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

This configuration illustrates rule order and syntax; unmatched requests go direct, so it is not a complete proxy setup. To send a type of request to a custom proxy group, define that group first, then use its exact name as the rule target. Match the capitalization and spacing used in the configuration. no-resolve means the core should not trigger DNS resolution solely for that IP rule. It does not mean the request will never involve DNS or disable all address matching.

Manage Proxy Groups and Rule Sets Separately

Proxy groups choose an outbound; rules choose a proxy group. A manual selection group is useful when you want explicit control over the current route. Automatic testing and failover groups depend on their test targets, intervals and decision logic. A reachable test target does not guarantee that the service you need will work; apps can be affected by protocol, region, authentication or remote restrictions. Do not treat one test result as proof that real traffic works, or set testing intervals too aggressively just to see changes sooner.

For larger rule sets, rule providers can help organize updates, but the resource type must match how it will be used. A domain list, an address list and a resource containing complete rule conditions use different formats; changing only the download URL is not enough. After defining a provider, reference it in the corresponding rules or the downloaded file will not affect routing. Check the path, name and behavior type together. If a resource fails to parse, whether the previous version remains available depends on the client and core; check the logs to see what actually happened.

Use Match Results to Troubleshoot Routing

Before changing anything, note the destination domain, actual target address, matched rule and final proxy group. A webpage often requests multiple domains for its main content, static assets and authentication, so changing only the main domain may not fix the whole page. Check which individual requests fail instead of routing an entire service by one suffix rule. For local network devices, verify the actual subnet too; the private ranges in an example will not cover every home, business or virtual network.

Rule updates also have supply-chain implications. Choose rule sources you can understand, know which categories they cover, and check whether updates can change where traffic goes. Combining multiple large rule sets can make overlaps and duplicates difficult to maintain; more rules do not necessarily mean more accurate routing. Start with a small set that addresses clear needs, then add exceptions based on connection logs. For each new rule, document its purpose and verify key apps still behave as expected after updates.

7. TUN and DNS: Traffic Capture and DNS Resolution

First, Confirm That You Need TUN

TUN routes traffic through a virtual network interface and can help with apps that do not follow system proxy settings. It is not a universal fix for network problems. Enabling it involves routing, permissions, DNS and other networking software, so it is more complex than using a local proxy port. Get the regular proxy path working first, then enable TUN and compare which traffic it captures. A mobile system VPN interface and a desktop virtual network adapter differ in permissions and implementation; do not assume they use the same setup steps.

Desktop clients may use a service component to get permission to create an interface and change routes. Before enabling TUN, check the service status and system prompts instead of relying on the switch indicator alone. Running an enterprise VPN, container network or another tunnel at the same time can cause routing or DNS conflicts. Test with only one traffic-capture method enabled and note the original routing behavior. If you are managing a remote device, prepare a recovery path first so a route change does not cut off your connection.

# mihomo TUN snippet: check client service and platform support before merging
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

This snippet is not a universal, cross-platform switch. auto-route configures related routes automatically, while auto-detect-interface helps determine the outbound interface. The result still depends on the operating system and network. If the client manages these fields through its interface, choose one persistent configuration method to avoid conflicting overrides. If the connection breaks after switching between Wi-Fi, Ethernet or a hotspot, check interface detection and route updates before changing the subscription.

How DNS and Fake-IP Fit Together

DNS translates domain names into addresses and provides context for domain-based routing and outbound selection. System DNS, browser encrypted DNS, client DNS and remote resolution may all be in use, so first establish which path a query actually takes. Capturing traditional DNS ports in TUN does not mean encrypted DNS inside every app is captured too. A result from one diagnostic page is not enough to prove that all requests are leaking or resolving correctly.

Fake-IP mode assigns a virtual address to a domain. The core uses its mapping to recover the domain and handle the connection. These addresses are not the website’s real server addresses, so seeing one does not by itself indicate a DNS problem. Some local network discovery, device authentication and special protocols may not work well with this behavior. Add a filtering exception for domains with a confirmed compatibility issue rather than disabling the entire mode. Keep exceptions narrow and verify one destination at a time.

There can also be startup dependencies between DNS upstreams, proxy server hostname resolution and direct-connection DNS. If resolving an upstream requires the proxy, while the proxy’s hostname depends on that same upstream, the configuration can form a loop. Specify which resolver is used to establish proxy connections and which handles regular traffic, using fields supported by your core. Do not combine upstream lists from unknown sources indiscriminately. More servers do not guarantee consistent results and may add latency and troubleshooting complexity.

Verify Traffic Capture and Recovery on Exit

After enabling TUN, check whether apps that previously bypassed the core now appear in its connection log, then verify their rules and DNS behavior. For local network access problems, check subnet routes, address conflicts and domain exceptions. If problems occur only after changing networks, check the outbound interface and DNS cache. After disabling TUN, confirm that the virtual interface, automatic routes and system DNS have been restored. Do not keep adding rules before recovery is confirmed, or a traffic-capture issue may look like a routing problem.

8. Routine Maintenance: Updates, Backups and Layered Troubleshooting

Track Updates by Component

At a minimum, distinguish updates to the client, core, full subscription, proxy providers and rule resources. Client updates affect the interface, integrations and platform support; core updates affect protocols and network behavior; resource updates change configuration content. A completed update in one place does not mean all components are current. To avoid introducing compatibility issues on multiple layers at once, update resources and verify them first, then update the application separately.

Before updating the application, save your current configuration, overrides and important settings, and note your connection method and ports. A backup should contain what you need to restore your setup, but never go in a public repository or group chat. A client’s export feature may omit system service state, external files or environment variables, so check what it includes before restoring. For file-based providers, back up the files referenced by relative paths too. Without the resource directory, a migrated configuration may parse correctly but fail to find its resources.

Narrow Down the Problem by Where It Occurs

If a webpage will not load, quit the client, restore system settings and test your basic connection first. If that also fails, investigate Wi-Fi, the gateway, a captive portal or your network provider. Once the basic connection works, check whether the local port is listening, the app’s connection reaches the core, a rule matches and the outbound succeeds. Following this order separates traffic that never reached the core from traffic that failed afterward, without changing every setting at random.

A failed subscription update and a failed service connection may be unrelated. Subscription authentication may have expired while an existing configuration still works; a service outbound may fail while the subscription endpoint remains reachable. Record exactly what failed, what action you took and the error category. A timeout, connection refusal, DNS failure and authentication error mean different things—not simply “slow network.” If the log is long, narrow it down to one repeatable action and extract the relevant time window.

Speed, Latency and App Performance

Latency in a connection test reflects one result for a specific target and method; it does not measure download speed, stability or the experience across all websites. To investigate slow speeds, keep the network and test target fixed, then compare direct connections, different outbounds and actual transfers in the target app. Wi-Fi signal, concurrent downloads, remote limits and network congestion can all be bottlenecks. Repeated speed tests can consume resources; observing normal app performance is often more useful than chasing a single test result.

If only one app is affected, start with its own proxy settings, DNS resolution and connection cache. If all apps fail at once, check the core, traffic entry method or upstream network. If only rule mode fails while global mode works, focus on matched rules, proxy groups and the related DNS path. Keep other conditions unchanged in each comparison and record what you did to restore service. A restart may fix things temporarily, but you will need evidence from before the restart to continue troubleshooting.

Recovery and Maintenance Notes

Keep a known-good configuration baseline and record the purpose, location and rollback method for each local change. When a problem occurs, export the necessary logs before reverting the most recent change; do not delete every data directory first. Confirm that the client can exit, the system proxy can be disabled and TUN routes can be restored before loading the baseline. If the problem appeared only in the new configuration, merge changes one at a time to identify the field that caused it rather than relying indefinitely on an old subscription that no longer updates.

9. Advanced Setup: Configuration Layers and Core Operations

Move from Getting Connected to Understanding the Results

Advanced setup does not have to start with more parameters. Start by being able to explain a single connection. Choose an app you know, then record how it connects, which domains it requests, which rule matches, which proxy group is selected and whether DNS follows the expected path. Once you can verify each step consistently, add rule providers, complex proxy groups or a standalone core. More features mean more dependencies; without a way to observe them, extra features only make problems harder to find.

Separate configuration into layers for resource sources, shared policy and device-specific settings. Remote resources hold content that needs regular updates; shared policy handles routing needs common to multiple devices; the local layer manages ports, paths, interfaces and permissions. This makes migration easier than copying an entire runtime configuration and reduces the risk of subscription updates overwriting local settings. Follow the client’s own merge mechanism: this general approach does not mean every client uses the same override syntax.

Before Running the Core Directly

On servers and routers, you can run mihomo directly, but you will need to manage the configuration directory, process, logs, permissions and startup order yourself. Features previously handled by a graphical client—especially system proxy integration, service management and resource download status—will not appear automatically. Validate a minimal configuration in the foreground before setting up a system service. Keep standard output and error output available if startup fails, so a silent background exit does not leave you with only an unreachable port to investigate.

# Check which parameters the current core supports
mihomo -h

# Check the configuration in the current directory, then start in the foreground
mihomo -t -d . -f config.yaml
mihomo -d . -f config.yaml

These commands assume the executable is on your system PATH and that the current directory contains the configuration and its resources. The working directory specified by -d affects relative path resolution. If the service runs as a different user from your interactive terminal, it may not be able to read the same files. A configuration check can find some syntax and reference errors, but cannot prove that remote resources are reachable, routing permissions are sufficient or a real request will succeed. Before setting up a service, verify a complete request and plan how to stop and roll back.

LAN Access, Control Interfaces and Router Setup

To let other devices use a proxy on your machine, consider the listening address, LAN access setting and firewall scope together. Opening a port alone does not complete the setup, and you should not expose a proxy port directly to the public internet. Restrict access to trusted subnets, add authentication if needed, and check which methods the client actually supports. Protect the external control interface separately instead of mixing configuration management with the regular proxy entry point. Check the core documentation to understand which features the control plane can access.

Router deployments also depend on whether the device acts as the main router or a side router, as well as on client gateways, DNS assignment and the return path. Running a core on a side router does not mean LAN devices are sending traffic to it. First determine where devices get their gateway and DNS settings, then check the transparent proxy path, and only then add routing rules. If the home network has multiple DHCP servers, resolve address assignment conflicts first. For an overview, see Running mihomo on OpenWrt and Side Routers. A desktop configuration is not a complete router setup.

Criteria for Ongoing Maintenance

Automated updates should include configuration checks, successful loading and rollback on failure—not just scheduled downloads followed by an overwrite. Keep the last known-good files if resource downloads fail; stop deployment if a configuration check fails; and verify key requests after reloading. Keep a change log for rule maintenance, but never commit resources that contain credentials to a public repository. If you use version control, track only redacted rules and override logic, and supply sensitive inputs through protected local configuration.