Clash Quick Start:
Import a Subscription and Test Your Connection
Follow this order: import a configuration → choose a mode → connect → test a request. If you’ve installed a client and have a compatible subscription ready, allow about 10 minutes for the initial setup.
Before you begin, get a Clash-compatible subscription link from your service provider or a working YAML configuration file. The client reads the configuration, routes traffic, and establishes proxy connections; installing it does not create a subscription or provide nodes automatically. A server address alone is usually not enough to connect—you’ll also need the protocol, port, and authentication details.
Subscription links may contain access credentials. Don’t post them in public comments, online conversion tools, or screenshots. Before sharing a problem, hide link parameters, node passwords, and personal information. The examples below explain how to configure a client; they don’t provide a working proxy service.
Import a Subscription and Set It as Active
Open the client and go to “Configuration,” “Profiles,” or “Subscription.” Choose “New,” “Add,” or “Import from URL,” then paste the complete subscription link into the URL field. Give it a recognizable name, such as “Daily setup”; the name only affects how it appears in the list. Make sure there are no extra spaces, line breaks, or punctuation copied from a chat app, then click Import or Download.
Wait for the client to download and parse the configuration. When it’s done, the list usually shows a name, source, or last-updated time. Seeing a new entry doesn’t mean it’s active: select it and choose “Enable,” “Use this configuration,” or the equivalent. Some clients mark the active entry with a check; others show its name on the overview page.
Check Proxy Groups Before Connecting
Open the “Proxy” page and check for the groups defined in the configuration, such as Proxy, node selection, or automatic selection. Names depend on the configuration author and may differ from the examples here. Expand a group to see its nodes or subgroups. If the page is empty, shows only a direct-connection option, or still displays groups from an older configuration, return to the configuration page and verify the active selection. Don’t keep toggling the system proxy.
For a local file, choose “Import from file” or “Import configuration,” select the relevant .yaml or .yml file, then activate it as described above. Importing a local file doesn’t turn it into a remote subscription. If its nodes change later, reimport the file or use the remote provider update mechanism already defined in the configuration.
Handle Download and Parse Errors Separately
“Download timed out” or “Unable to fetch subscription” usually means the configuration hasn’t been retrieved. Check your device’s network, the link’s expiration, and your provider’s status. Some subscription URLs may be inaccessible on certain networks; use a valid retrieval method provided by your service. Don’t give credential-bearing links to unfamiliar conversion services. A page that won’t display in your browser doesn’t necessarily mean the subscription is invalid—the endpoint may require a particular request method.
“Parse failed” or “Unsupported field” means the client received the content but can’t read it in its current format. Common causes include importing a webpage URL, receiving a login page, or using a subscription format incompatible with the core. Ask your provider for a Clash- or mihomo-compatible format. For indentation and fields, see the YAML guide; there’s no need to rewrite the entire file just to get connected.
Once the configuration is active and its proxy groups expand, move on to the next step. Remote subscription updates may overwrite manually edited nodes and rules, so leave the original content unchanged during initial setup. If you need custom rules later, learn how your client handles overrides or merges. For more about subscription sources and update issues, see subscription FAQs.
Choose a Rules Mode and Proxy Route
On the “Proxy” or “Overview” page, find the mode switch and set it to “Rule.” Rules are applied in the order defined in your configuration: some destinations connect directly, while others go through a proxy group. Keep the subscription’s default rules for your first setup. Confirm the full connection works before adding your own routing requirements.
Mode and node selection are two separate settings. The mode determines whether requests are handled by rules; a proxy group determines which route to use when a proxy rule matches. Keep Rule mode, expand the default proxy group, and select a known working node. If the group offers “Auto Select” or “Fallback,” you can choose that subgroup instead. Some groups may default to DIRECT, which means that group connects directly.
Make Sure You’ve Selected a Node in the Group That’s Actually Used
A configuration may include separate groups for web, media, messaging, and other traffic. Changing one group won’t necessarily affect every request. Find the main proxy group referenced by the other groups, or choose the default route recommended by your subscription provider. If you can’t tell how the groups are connected, don’t change them at random. Later, use connection logs to trace a request’s proxy chain and adjust the relevant group.
The client’s connectivity test can help rule out clearly unavailable options, but a successful test only confirms that a specific test request got a response. It doesn’t guarantee access to every website. Choose a route that passes the test, then check the page you actually need. Repeated tests and frequent node changes make issues harder to diagnose; change one thing at a time and compare results.
When to Use Rule, Global, and Direct Modes
“Global” sends all traffic that reaches the core through the global policy. It doesn’t automatically capture traffic from every app on your device, and it isn’t the same as enabling TUN. To check whether a routing rule is causing a problem, switch to Global temporarily and select a working node in the global group. When you’re done, switch back to Rule mode so traffic that should connect directly doesn’t unnecessarily use the proxy.
“Direct” sends traffic that reaches the core straight to its destination. It doesn’t turn off the client or remove the proxy settings in your operating system. To stop proxy routing entirely, follow Step 4 to turn off the system proxy or disconnect on mobile—don’t just switch the mode to Direct.
For definitions of “node,” “proxy group,” and “rule,” see the glossary. If you need to write rules, change rule order, or configure remote rule sets, see the YAML guide. None of these are prerequisites for your first connection.
Enable the System Proxy or Connect on Mobile
Return to the client’s overview page and make sure the core started without errors, then enable a traffic entry point. On desktop, start with “System Proxy”; on mobile, use “Connect” or the start button. For your first attempt, use one clear connection method. Don’t enable another VPN, proxy client, or separate browser proxy at the same time, as multiple tools may overwrite the same system setting.
Desktop: Start with the System Proxy
In your Windows, macOS, or Linux client, find and enable “System Proxy.” Some clients may ask you to install a helper service or allow changes to network settings; follow the operating system’s permission prompts. Make sure the prompt comes from the client you’re using. If you denied a required permission, the switch may look enabled even though the system setting wasn’t applied. Check your system’s network proxy settings to confirm.
The system proxy usually directs apps that honor system settings to a local proxy port. Most browsers can use it, but app support varies. Command-line tools, games, and apps with their own networking stack may not follow it. Test with a browser first; one app not using the proxy doesn’t necessarily mean the node is down. You’ll find a separate terminal test in the next step.
If the client reports that a port is already in use, close any other proxy tool that may be listening, then restart the current core. If you need to change the port, check the actual HTTP or mixed-port value in settings and update any apps where you entered a proxy address manually. Don’t assume an example port matches your setup; use the value shown in your client.
Android and iOS: Approve the System VPN Request
On mobile, select the configuration you want to use and tap Connect. The first time you start it, the system usually asks permission to create a VPN connection or add a VPN configuration. Approve the request, then check the connection status in the client. This VPN permission creates a route for system traffic; it doesn’t make a subscription usable by itself. You need a valid configuration, a working route, and approval.
If the connection turns off as soon as you enable it, check the client’s error message first, then see whether another VPN app is already using the connection. On Android, if per-app proxying is enabled, make sure the browser you’re testing is included; also check whether background activity is restricted. On iOS, confirm that the selected configuration is the one being started. Don’t keep reinstalling the app instead of checking the error.
Enable TUN Only If You Need It
If the browser works but an app you need ignores the system proxy, consider learning about TUN. TUN uses a virtual network interface to route traffic and may require service permissions, routing, and DNS settings. Turning it on doesn’t guarantee that every app will be covered. For your first setup, don’t enable both the system proxy and TUN. Establish a connection you can verify first, then expand it one step at a time using your client’s instructions.
Office networks, remote desktops, and local devices may depend on specific routes, so keep your existing connection details before enabling TUN. If you need to adjust DNS or Fake-IP, see the DNS settings reference and Fake-IP guide. Once the connection entry point is enabled, test an actual request; a lit switch alone doesn’t confirm the setup works.
Test Your Browser, Terminal, and Network Recovery
First open a page that normally works without a proxy to make sure your basic connection is intact. Then open a destination that actually requires a proxy. Use a new tab or reload the request to avoid relying on browser cache. Keep the same node and mode throughout the test so you can identify which setting is responsible if the results differ.
Use Connection Logs to Trace Traffic
Open the client’s “Connections” page and revisit a page in your browser. Look for the destination domain. Short-lived requests may disappear quickly, so use search, history, or logs to find them. Check the destination, matched rule, and proxy chain—not just whether the client says it’s running. A matching entry confirms that the request reached the core.
If the log shows DIRECT, first check whether that matches the configuration’s intent. Rule mode allows some sites to connect directly; that isn’t a connection failure. If the destination should use a proxy but goes DIRECT, check the matched rule and relevant proxy group. If the proxy chain is present but access still fails, check the node, destination service, and specific log errors. There’s no need to change DNS right away.
If you can’t find the browser request at all, first check whether the system proxy was applied, whether the browser has separate proxy settings, and whether an extension is overriding the proxy. On mobile, also make sure the app you’re testing is included in the traffic-routing scope. Switching nodes usually won’t help here because the request may never have reached the client.
Test the Terminal Separately
Command-line tools don’t always use the system proxy. If the client’s actual mixed port is 7890, run the one-time test below. If your port is different, replace it with the value shown in settings. This command uses an HTTP proxy for this request only; it doesn’t change your terminal environment permanently and doesn’t require administrator privileges.
curl --proxy http://127.0.0.1:7890 --head https://example.comexample.com is only an example domain to demonstrate the command; it isn’t a proxy service. To test a specific site, replace it with the HTTPS URL you want to visit and check the client’s connection log at the same time. Receiving response headers means that request got a response from the address; the proxy chain in the connection log confirms the route. Different sites may return different status codes.
If the request works when you explicitly specify a proxy but fails when you run the terminal command directly, the terminal probably lacks proxy settings—not a working subscription. You can later configure proxy arguments or environment variables using your tool’s documentation. Don’t add generic commands to every shell’s startup file: the right settings depend on the tool, port type, and variable scope. Confirm what you need before changing anything.
Narrow Down the Problem Step by Step
If a page won’t load in your browser, first check whether a request appears in the connection log. If it does, check the matched policy; if that’s correct, try a known working node. If only Rule mode fails, temporarily switch to Global for comparison and make sure the global group has a working proxy selected. If Global works but Rule doesn’t, check the rules and group selection. If both modes fail, check the node, network, and logs.
Don’t change the mode, DNS, port, and TUN settings all at once. Change one thing at a time, repeat the same request, and record the result; that way, any difference helps narrow down the cause. For more troubleshooting categories, see the FAQs. Once you’ve identified a configuration field, consult the relevant section of the YAML guide.
Finish by Testing Disconnect and Recovery
After verifying the connection, turn off the system proxy on desktop before quitting the client; on mobile, tap Disconnect. Visit a site that normally connects directly and confirm your network is back to normal. If the browser can’t connect after you quit the client, check whether the system still points to a local proxy address and disable any leftover manual proxy settings. Before switching clients in the future, remove the old client’s traffic entry point first.
When you update a subscription later, first confirm that the correct configuration is still active. Check whether the original proxy groups are intact and whether your selections have changed, then test the same destination again. Keeping this short process in mind makes it easier to switch devices and troubleshoot than memorizing the button locations in a particular client.