Clash Setup Guide

Before You Begin: Prepare the Client and Subscription

The installer provides the client app; it doesn't include working remote nodes. Before you begin, get a subscription URL from your provider or a compatible configuration file containing nodes, proxy groups, and rules. Subscription URLs often contain personal authorization details, so treat them like account credentials. If you need to share a screenshot, hide the full URL, QR code, and authorization parameters. Leave only the error message and relevant setting names visible.

When you first open the client, check that the main window loads and locate the configuration, proxy, settings, and logs pages. Some desktop clients keep running in the system tray or menu bar after you close the window, so closing it doesn't necessarily stop the core. For now, leave the system proxy and TUN disabled. Enable system access only after the configuration has loaded to avoid losing connectivity before setup is complete.

If another proxy, VPN, or network-routing app is running on your computer or phone, save its settings and disconnect it before testing Clash. Multiple tools can change the system proxy, routes, or DNS at the same time, making the actual connection path differ from what the interface shows. Organization-managed devices may also enforce proxy policies. Follow your device administrator's requirements rather than overwriting managed network settings.

The steps below assume you already have a compatible subscription. Confirm each result before moving on: first load the configuration, then check that proxy groups are available, enable system access, and finally review actual connection records. If you need to clarify terms such as “subscription,” “node,” or “core,” start with the glossary. There's no need to edit the entire YAML file just to get connected for the first time.

Step 1: Import and Enable a Subscription

Add a Subscription URL

Copy the Clash- or mihomo-compatible subscription URL from your provider's account page. Open the client's subscription or configuration page and look for “Add,” “New configuration,” or “Import from URL.” Give the configuration a recognizable name, paste the URL into the address field, then click Download, Import, or Save. If the client says the URL is invalid, check for extra instructions, leading or trailing spaces, or line breaks. Don't manually remove or change its authorization parameters.

Wait for the download to finish. The configuration list should show the name you entered, along with details such as the update result, last updated time, or file size, depending on the client. Seeing an entry in the list is only part of the import process: click “Use” or “Enable,” or select the configuration card. Then open the proxy page and confirm that the subscription's proxy groups and nodes appear. That confirms the configuration has loaded locally.

Some clients distinguish between a “remote subscription” and the “active configuration.” Updating the remote entry may not switch the active configuration, and a newly added subscription may be saved without being enabled. If the proxy page still shows old nodes, return to the configuration list, check which item is selected, and enable the new configuration. Then check the logs for parsing errors. A new card in the subscription list alone doesn't mean the configuration is active.

Import a Local File and Fix Format Errors

If you received a local .yaml or .yml file, use the “Import file” option or drag and drop it if the client explicitly supports that. You still need to enable the configuration after importing it. A list of individual node URLs is not the same format as a full Clash configuration, which usually also defines proxy groups and rules. When choosing a subscription type, use the client-compatible format specified by your provider.

“Download succeeded, but parsing failed” usually means the server returned content the current core can't read. The response might be a login page, an expired authorization message, a format intended for another client, or a configuration with fields the core doesn't support. Start with the specific error in the logs, then ask your provider which subscription format to use. For protocol support, see core and configuration compatibility. Don't delete nearby fields at random just to force the configuration to load.

If the download fails outright, first determine whether the problem is the URL, authorization, or network. Make sure the URL belongs to your current account and is still valid, then try again on a regular network. Some clients offer an option to “update subscriptions through proxy,” but you may not have a working proxy during initial setup. Enabling it blindly can make updates depend on a connection that isn't available yet. Never send a private subscription URL to an unfamiliar online converter. If conversion is necessary, find out how the service handles and stores URLs first.

Step 2: Choose Rule Mode and a Node

Open the proxy mode option on the main screen or settings page. For your first setup, choose “Rule” or Rule mode. It uses the rules in your configuration to decide which policy handles each connection: some destinations may connect directly, while others go through a proxy group. This selects a connection policy; it does not enable system access. Until you turn on the system proxy or mobile connection, other apps may still connect directly to the internet.

“Global” mode usually sends all connections entering the core through the global policy. It's useful for a temporary comparison, but you still need to select a node in the relevant proxy group. “Direct” mode usually connects directly to destinations and can't tell you whether a remote node is working. Change one variable at a time: start in rule mode and verify a normal connection, then switch to global mode briefly if needed. Restore rule mode when you're done.

Choose an Available Node in a Proxy Group

Open the proxy or proxy groups page and find a group that lets you choose a node manually. Group names are set by the configuration author: yours might be called “Proxy Selection,” or something else, and it may not be named PROXY. Expand the group, select a node, and confirm that the selection indicator moves to it. Some groups contain other proxy groups as options; if so, check the final node selected in the nested group. Otherwise, you could change a group that your rules don't actually use.

Auto-select, fallback, and load-balancing groups choose an outbound connection according to their configuration, and may not let you pin a specific member. For initial troubleshooting, use a manual selection group if one is available to keep a single node fixed and avoid interference from automatic switching. You can restore the automatic group afterward. For how proxy groups connect to rules, see the rule-based routing guide. You don't need to rewrite the subscription's routing rules here.

The client's test button can help identify nodes that are clearly unreachable, but the result reflects only the test address, connection path, and conditions at that moment. A response time doesn't guarantee that every website will work, and a timeout doesn't necessarily mean the node is permanently down. Verify your chosen node with an actual app and the connection logs. Don't change the mode, DNS, and TUN together just because the test results are reordered; changing several things at once makes the cause harder to pinpoint.

If the proxy page shows only policies such as DIRECT and REJECT, but no expected nodes, go back to Step 1 and check that the subscription loaded correctly. If the nodes appear but selecting one immediately causes an error, check whether it relates to the protocol or a configuration field. Before moving on, confirm the current mode, the selected proxy group, and the node or outbound currently in use.

Step 3: Enable the Connection and System Access

Desktop: Check the System Proxy First

First, check whether the client reports that the core is running, or look in the logs to confirm that a local proxy port is listening. Being able to open the client interface doesn't mean the core started successfully. A port conflict or configuration parsing error can prevent it from running. Once it's running, turn on “System proxy” or “Set as system proxy” to route connections from browsers and apps that support the system proxy through the local port.

Common configurations use a mixed port for both HTTP and SOCKS connections, but the actual port depends on your client settings. Don't assume every installation uses 7890. Check the mixed or HTTP port in settings, then confirm that the operating system's proxy address points to 127.0.0.1 and the correct port. If the client configures this automatically, you usually don't need to enter anything manually. Check the system network proxy settings only if automatic setup fails or you're troubleshooting.

After enabling the system proxy, reload the browser page. A separate proxy extension may override system settings, so temporarily disable it or set it to use the system proxy. Command-line tools, some games, and other apps may not use the system proxy, so success in a browser doesn't mean every app will follow it. Verify the browser first, then decide which other apps need to be routed.

Mobile: Approve the System Connection Request

On mobile, tap the connection toggle on the home screen after loading the configuration and choosing a node. The first time you connect, the operating system will usually show a VPN authorization prompt. Check that it comes from the client you just installed, then approve it. The VPN interface is how the app connects to the system network; it doesn't mean the subscription includes a particular protocol. A VPN indicator means the system interface started, but you still need to verify routing and the connection in the next step.

If you cancel the authorization prompt, return to the client, turn on the connection again, and approve it. If another VPN app is already connected, disconnect it before retrying. Mobile operating systems may limit background activity, particularly when the phone is locked or in battery saver mode. If you actually experience disconnects in the background, check the client's background permissions in system settings. Don't change every battery setting before there's a reason to.

Enable TUN Only If You Need Broader App Coverage

TUN uses a virtual network interface to route connections. It's useful for apps that don't read the system proxy settings. Desktop clients may require you to install a service, grant administrator permissions, or confirm creation of the virtual interface. The steps and permissions vary by operating system, so follow your client's prompts. Don't keep toggling the switch to get past a permission error; first confirm that the service is installed and the core supports the required configuration.

For your first test, choose one clear connection method, such as the desktop system proxy or the mobile VPN connection. When you enable TUN later, check whether the client automatically changes the system proxy or routes. Whether both can run at the same time depends on the client, so don't assume there's one rule for every setup. For details on DNS routing, route scope, and core capabilities, see the protocol and core technical reference.

Step 4: Verify Rules and Connection Results

Open the client's connection list or logs, then use a browser to visit a website that should go through the proxy under your current configuration. Choose a page that doesn't require a login and reload it to establish a new connection. An existing tab may reuse an old connection, and cached content can make a page appear to load without a new network request. A successful-looking page alone doesn't confirm the proxy path.

Find the matching domain or address in the connection list and check the matched rule, proxy group, and final outbound. The interface may show rule types such as DOMAIN-SUFFIX, GEOIP, or MATCH; these identify the matching criteria. DIRECT means the connection went directly, while REJECT means it was blocked. A proxied connection typically shows a proxy group and node name. A new log entry, an expected rule match, and a successfully loaded page together provide a more reliable confirmation that the setup works.

Next, visit a destination that should connect directly under your configuration and check that it matches a direct policy. Rule mode can use different outbounds for different destinations, so some pages showing a direct connection is usually expected. If a destination incorrectly goes direct, check the rules and proxy groups instead of repeatedly switching nodes. When an app connects to multiple domains, check the related connections too; one connection alone doesn't reveal the app's entire route.

Narrow Down the Problem by Symptoms

If no new connection appears in the list when you visit a page, check system access first: whether the browser uses the system proxy, whether a proxy extension overrides it, whether the mobile VPN is still connected, and whether the expected TUN route is enabled. Some clients show detailed records only at certain log levels. Distinguish between “the record isn't displayed” and “the connection never reached the core”; an empty list alone isn't enough to tell.

If a record appears but the connection repeatedly times out or errors, the request has at least reached the core. Next, check the selected node and whether it can reach the destination. Keep the mode and connection method unchanged, switch to another available node, and try again. If only one website fails, check its rules and related domains. If all proxied destinations fail but direct connections work, check the subscription, node authorization, or provider status.

If the connection record shows the expected policy but the browser reports a certificate or security error, don't disable certificate validation just to get connected. Check the device's date and time, the domain you visited, and system trust settings. If you need support, provide the client name, operating system, connection method, exact error message, and steps to reproduce it. Logs may contain domains, addresses, or subscription details; before sharing them, keep only the lines relevant to this error and remove sensitive information.

After verification, keep a record of the settings confirmed to work: active configuration, rule mode, selected policy, and connection method. If Clash stops connecting later, compare the current setup against this known-good state. Change one setting at a time and retest. This makes problems easier to trace than changing the port, DNS, node, and mode all at once, and helps prevent a working configuration from becoming an unknown one.

Everyday Use: Disconnect and Update Your Subscription

To fully stop a desktop client, turn off the system proxy or TUN first, then quit using the client's exit option. If you end the process directly, the system may still point to the local proxy port, and your browser may keep trying to connect to a service that has stopped. If that happens, reopen the client and disable the system proxy, or remove the manual proxy setting it added in your system network settings. Don't remove network settings on a managed device without authorization.

On mobile, disconnect using the client's connection toggle or the system VPN settings. Next time you use it, check that the expected configuration and node are still selected, then reconnect. You don't need to import the subscription again each time. If a system update requires you to authorize the connection again, follow the new prompt and repeat the connection check.

To update a subscription, open the configuration list, select the relevant entry's update button, wait for the result, and confirm that the active configuration has refreshed. An update may add or remove nodes, change proxy groups, or overwrite configuration content; a previously selected node may no longer exist. If the client supports overrides or configuration merging, keep your custom settings in a clearly separate section. Don't rely on temporary edits to a remote file as a permanent solution.

The basic connection setup is complete. For definitions, see the proxy and rule-based routing glossary. To compare protocols, learn about mihomo core capabilities, or adjust rules, see the technical reference. Before switching clients, note your current connection method and configuration source. Then choose a platform-specific installer from the downloads page so you don't mistake client differences for a failed subscription.