Clash Setup Guide

Step 1: Import a Subscription

Get your Clash subscription URL from your service provider, or find a YAML configuration file compatible with your client’s core. The client loads the configuration, applies its rules, and establishes proxy connections; installing it alone does not give you a working proxy. Before importing, make sure your device can access regular websites with the proxy off, and check that your subscription is still active. This makes it easier to tell a configuration issue from an existing network problem.

Import a Configuration from a URL

Open the client’s “Configuration” or “Subscriptions” page. Choose “Add,” “Import,” or the plus button, then select “Import from URL.” Paste the full link, give the configuration a recognizable name, and click Save or Download. The name is only for local organization and does not change the subscription. Check for extra spaces, line breaks, or text added by your messaging app. Don’t remove anything after the question mark in the URL; those parameters may be needed to identify the subscription.

Wait for the download and parsing to finish. A successful import adds a new entry to the list; some clients also show its last update time or traffic information. Select the entry and choose “Enable,” “Use,” or “Set as current” until you see it marked as active. Saving a subscription to the list isn’t enough—the core must load it to use its nodes and rules. Next, open the “Proxy” page and check that proxy groups and their options are available before continuing.

If the download fails, check the subscription status on your provider’s subscription management page before trying to update it again. A URL that opens in a browser isn’t necessarily a subscription URL; login, purchase, and account pages can’t be imported as configurations. If the client reports an incompatible format, choose one explicitly labeled Clash or mihomo by your provider. Don’t submit subscription URLs containing personal identifiers to an unfamiliar online converter.

Import from a File or QR Code

If you already have a local configuration, choose “Import from file” on the same page and select a file ending in .yaml or .yml. Wait for the client to parse it, then set it as the active configuration. A file extension is only a clue; the contents must still follow the configuration syntax. A plain-text list of nodes or a webpage saved to a file won’t become a Clash configuration just by renaming it. If the file depends on remote rule sets or proxy providers, the client may need an internet connection to fetch them on first load.

If your client supports QR codes, you can also choose “Scan QR code.” Check what the scan finds: a QR code might contain a subscription URL or a share link for a single node, and these aren’t interchangeable full configurations. Confirm the imported configuration includes the nodes and rules you need, then enable it. Subscription URLs are usually tied to your account, so redact the full URL and its parameters from screenshots, logs, and support requests.

For your first connection, use the subscription as provided; don’t edit rules or add overrides yet. Once you’ve confirmed that it works, configure automatic subscription updates. A static local file usually won’t get new nodes automatically over time. For the difference between subscriptions and configuration files, see the glossary. For now, just confirm that the configuration is active and its proxy groups can be expanded, then move on to choosing a mode.

Step 2: Choose a Proxy Mode

Return to the client’s home screen or open “Settings” and look for “Operating Mode,” “Proxy Mode,” or “Mode.” For a first-time setup, choose Rule. This mode is usually labeled “Rule” in English and “规则” in Chinese. The mode determines which route traffic takes, but it doesn’t load a subscription or enable the system proxy. Set the mode and proxy group before routing system traffic to avoid confusion from switching settings mid-connection.

Select a Node in a Proxy Group

Open the “Proxy” or “Proxy Groups” page and find the main group used by your subscription’s rules. It might be called “Proxy,” “Node Selection,” or PROXY, depending on the configuration. Expand it and select an actual node. If it contains subgroups such as “Auto Select” or “Failover,” open one to check its available nodes. Group names don’t guarantee how traffic is routed; check the selected option and connection details.

If the main proxy group is set to DIRECT, a rule that points to that group may still connect directly. If it points to another proxy group, check that group’s selection too, until you can confirm the final route. Some subscriptions use separate groups for websites, streaming, and other traffic. You don’t need to change every group during initial setup—find the one used by your target site and check its selection instead of setting every group to the same node.

Click “Test Latency” or the test button beside the group, then wait for the results. A successful test can help you shortlist nodes, but the test endpoint, protocol, and node load all affect the result. Latency alone doesn’t determine how well a node will work for your traffic. Skip nodes that time out, select one that passes, and then test it by visiting a website. Even a successful latency test doesn’t replace the verification in Step 4.

Keep the Existing Rules

Rule mode checks rules in configuration order. Earlier rules usually take precedence, while the final fallback rule catches connections that haven’t matched anything else. So enabling Rule mode doesn’t automatically route every website outside your network through a proxy; that depends on the subscription’s rules. Keep the existing rules for your first connection, and check connection details if a particular site has a problem. For more on rule order, domain matching, and proxy group references, see how proxy groups work. Save complex edits until after you’ve verified the connection.

Step 3: Enable the Connection

Once you’ve confirmed the active configuration, operating mode, and proxy selection, enable traffic routing. First, check that the client reports its core is running and that the logs show a listening port or successful configuration load. If startup fails with a configuration parse error or port binding error, fix that first instead of repeatedly toggling the system proxy. Routing system traffic to a core that isn’t running can make websites unreachable.

On Desktop, Start with the System Proxy

Turn on “System Proxy” from the desktop client’s home screen, Settings, or tray menu. This usually points the system’s HTTP and HTTPS proxy settings to a local listening address. Browsers and apps that support and follow this setting will then route connections through the client. If the page shows a mixed-port of 7890, a common local address is 127.0.0.1:7890. Use the value shown in your current configuration and settings, though—don’t copy a port over an existing configuration without checking.

For your first test, run just one proxy client and temporarily disable browser extensions that set their own proxy. An older client may have left a different proxy address behind, sending system traffic to a port with no service listening on it. If the client reports that a port is already in use, close the other app using it or change the listening port as supported by the client, then make sure the system proxy setting matches. A control port manages the core; don’t enter it in your browser’s HTTP proxy settings. For details, see port settings explained.

After enabling the system proxy, don’t turn on TUN at the same time. For most browser tests, start with the system proxy; it’s easier to inspect the connection path. Some command-line tools, games, and apps with their own networking stacks may ignore the system proxy. If those apps aren’t routed through the client, that doesn’t necessarily mean it’s broken. After confirming the browser works, configure those apps individually or enable TUN if needed.

Allow the VPN Connection on Mobile

Return to the client’s home screen and tap “Connect” or the start button. When the system first asks whether to add a VPN configuration or establish a VPN connection, verify that the request comes from the client you just installed before allowing it. Once authorized, check the client’s connection status and look for the VPN indicator in the system UI. The indicator confirms that a system tunnel is active, not that the subscription node can reach your target site. Continue with the connection test.

If another VPN, network filter, or packet capture tool is running, stop it before connecting. Mobile operating systems typically limit which services can route network traffic at a time, and competing services may cause repeated disconnects. If the connection drops mainly when the app is in the background, complete a foreground test first, then check battery management and background activity restrictions. Don’t disable unrelated system security features to troubleshoot a network issue.

Step 4: Verify the Connection

Keep the client running and open a new browser window. Visit an HTTPS site that should use the proxy under your current rules, then visit a site expected to connect directly. Don’t just refresh a page that’s been open for a while; existing connections or cached content can make the results misleading. A site loading is the first check. Next, confirm that its connection appears in the client and see which route it took.

Check Connection Details and Logs

Return to the client’s “Connections” page and look for the domain or destination address while the page is loading. Open the connection details and check the matched rule, proxy group chain, and final node. The visit is working as expected when the connection matches the intended rule, uses the selected proxy, and the page loads. A direct connection to a site expected to bypass the proxy may appear as DIRECT; that’s normal rule-based routing. You don’t need to switch to Global mode just to make every connection show a proxy.

Some clients show only active connections, so a short-lived request may disappear from the list quickly. Open the Connections page before visiting the site, or look for a record from the same time in the logs. A successful local listener entry only proves the core has started accepting connections. If a node connection fails, check the destination, error type, and selected route. Temporarily increasing log verbosity can help; restore your usual level afterward, and redact subscription URLs and personal network information before sharing screenshots.

An IP lookup can provide an additional check, but it can’t prove that every app is using the proxy. The lookup site itself is subject to your rules and may connect directly. Another app on the same device may also bypass the system proxy entirely. First test the specific site or app you need, then check its own connection record. Don’t assume one lookup result describes all traffic on the device.

Troubleshoot One Symptom at a Time

If a website won’t load and there’s no new connection in the client, first check whether the browser follows the system proxy, traffic routing is enabled, and the local proxy port matches. On mobile, check that the VPN is still connected. If system-wide routing is enabled but one app has no connection record, check that app’s own proxy settings. Don’t start by changing DNS or rules; traffic may not have reached the core yet.

If a connection appears but ends up going direct, return to Step 2 and check the mode, matched rule, and current proxy group selection. If the record shows the expected proxy node but the connection times out, choose another node in the same group and retry the same site. If that still fails and the log points to a DNS resolution issue, check your DNS settings. Change one thing at a time and repeat the same test so you can identify what affected the result.

For a quick comparison during initial testing, you can temporarily switch to Global mode, but first make sure the global policy selects an actual proxy node. If Global works but Rule mode doesn’t, check the rules and their proxy group references before assuming the whole subscription is broken. Switch back to Rule mode after testing and keep the working node selected. For specific error messages, see Troubleshooting. There’s no need to rewrite the entire configuration during your first connection test.

Restore Traffic Routing Settings Before Exiting

Once the connection works, note the configuration name, mode, and main proxy group. After a subscription update, check that they’re still set as expected. When you’re done, turn off the system proxy or TUN before exiting the desktop client. On mobile, disconnect the VPN from the client. If regular websites stop working after you exit, check whether the system still points to a local proxy address and restore its previous settings. There’s no need to immediately uninstall the client or reset your entire network.

Your initial setup is complete when the subscription is active, a proxy can be selected in Rule mode, traffic follows the expected route, and the website result matches the connection record. Add automatic updates, persistent overrides, and more detailed app routing later, one at a time. For long-term setup and maintenance on your platform, see the complete cross-platform installation and setup guide.