Clash Setup Guide

Before you begin: Check your configuration source and network

The client reads the configuration, applies its rules, and establishes proxy connections; it does not provide a working subscription by itself. Before you start, get a configuration URL from a trusted provider or your own service, and make sure it’s formatted for Clash or mihomo. A website login URL, payment page, or single protocol share link may not work in the subscription field. If the provider offers multiple formats, choose one that matches the client’s core.

Before connecting the proxy, visit a site you normally use to confirm your network is working, and check that your device’s clock is correct. Quit other proxy clients or VPNs that are routing traffic, and note any existing manual proxy settings. When multiple programs change system proxy or routing settings, an “On” indicator doesn’t guarantee requests are reaching the current client. For the first setup, keep the default port, DNS, and inbound settings. Get the simplest connection working before changing anything else.

Subscription URLs often contain access credentials, so treat them like account details. If you need help, share the client name, core, operating system, and type of error. Before sending a screenshot, hide the full subscription URL, node authentication details, and personal account information. Don’t upload private configurations to unfamiliar online converters. For more on protocol support and subscription format differences, see Protocol and Core Technical Reference.

Step 1: Import and enable a subscription configuration

Enter the URL and wait for the configuration to download

Open the client’s Subscription or Configuration page and look for “New,” “Add,” or “Import from URL.” Choose a remote subscription, enter a recognizable name, and paste the full subscription URL. Check the beginning and end of the URL, removing accidental spaces, line breaks, or punctuation added by a messaging app, but don’t alter its query parameters. If the client offers an update interval, keep the default for now. Set automatic updates after confirming a manual download works.

After clicking “Import” or “Download,” wait for the operation to finish. A successful import usually creates a configuration card with its name, last update time, or available actions. Seeing the card doesn’t mean it’s active: click “Enable,” “Use,” or the corresponding selection control, then confirm the active configuration has changed. Open the Proxy page and check for the proxy groups defined in that configuration. If only the default DIRECT option appears, check which configuration is enabled.

If you have a local YAML file, use “Import from file” to select it. Keep an original copy before importing so later edits don’t overwrite your only copy. Local files generally won’t update when the remote service changes; a remote subscription may replace its contents the next time it refreshes. For your first setup, avoid adding lots of rules directly to a subscription. If you later need persistent custom settings, look into the client’s configuration override or merge features.

Import failed? First identify whether it’s a download or parsing error

For a timeout or connection error, first check that the URL is still valid and your network can reach the subscription service. Whether subscription updates use a direct connection, system proxy, or client core depends on the implementation and update settings. Don’t assume that changing nodes will change the route used for updates. If downloading requires a working proxy but you don’t have a usable configuration yet, ask the provider for an initial import method. Don’t enable the system proxy before it’s configured.

For HTTP 401, 403, or 404 errors, check authorization, server restrictions, and whether the URL has expired; the provider’s documentation is the best source for what each error means. A YAML parsing error, unknown protocol, or unsupported field points to a problem with the configuration or core compatibility. Copy the relevant error text without credentials, then confirm the format and core type. Move on only after the subscription is enabled and its proxy groups appear, so you don’t mistake an import problem for a broken node.

Step 2: Choose a rule mode and proxy node

Once the configuration is enabled, open the “Proxies” or “Overview” page and find the mode selector. For your first setup, choose “Rule” (shown as Rule in English interfaces). Requests are matched against the configuration’s rules and sent direct, rejected, or routed through a proxy group as specified. Rule mode does not send every site through the same node or require you to switch modes for each visit, making it a good starting point for everyday use.

“Global” mode typically sends requests to a global proxy group, where you still need to select an outbound. It doesn’t automatically route every app through the client. “Direct” mode typically sends requests straight to their destination; it doesn’t turn off the system proxy or stop the core. Modes control how the core selects an outbound. The system proxy and TUN control how traffic reaches the core. Keep these two layers separate when troubleshooting so you know which setting to check.

Next, review the proxy groups. A manual selection group lets you choose a node; groups for automatic testing, failover, or load balancing follow their configured policies and may not support manual pinning. Find a selectable group used by the active rules, expand it, and click an available node. Confirm the selection indicator moves. Group names might be “Proxy,” “PROXY,” or a name chosen by the provider. You don’t need to rename anything to match this guide. If the selected option points to another proxy group, check that group for the actual node selection.

Run an availability or latency test if the client provides one. It can help rule out options that clearly can’t connect. A test measures one probe from the client to a specific target; it doesn’t tell you download speed, sustained throughput, or how well every site will work. A timeout may also be caused by the test URL or route. Choose a node that passes the test, then verify it with a real request after connecting. Don’t keep switching nodes based on milliseconds alone.

After choosing a node, leave the mode set to “Rule” and avoid changing rule order, DNS, and proxy group structure at the same time. If a site uses a direct connection, that may be exactly what the configuration intends—not a connection failure. The next step is simply to route app traffic through the client. Then use the connection log to see which rule matched. For protocol behavior, rule matching, and core compatibility, see the Technical Reference. There’s no need to rewrite the configuration before your first connection.

Step 3: Start the core and route app traffic

Desktop: Start with the system proxy

Return to the client’s Overview or Settings page and confirm the core is running without configuration errors. If there’s a Start button, click it; some clients start automatically when you enable a configuration. Then turn on the System Proxy option. It usually points the operating system’s HTTP proxy settings to a local listening port, allowing apps that use system proxy settings to send requests to the client. Make a new browser request after enabling it. Restart the browser if needed to avoid reusing an old connection.

On the Network, Ports and Inbound, or similar page, check the actual listening address and mixed port. A common example is 127.0.0.1:7890, but use the value shown by your client. mixed-port accepts both HTTP and SOCKS proxy requests on one port. If the startup log says the port is already in use, check for an older client or another listening process. If you need to change the port, update both the client’s inbound setting and any manual proxy settings in your apps.

You don’t need to enable “Allow LAN” for your first connection. That option is for other devices accessing the proxy on your computer; it doesn’t affect whether your local browser can use the system proxy. Leaving it off means fewer listening address, firewall, and access-control settings to troubleshoot. The external controller address is for managing the core, not for browser proxy traffic. Don’t enter a controller address such as 127.0.0.1:9090 in your browser’s proxy settings.

Mobile: Approve the system VPN prompt

On mobile, enable the configuration and select a node, then return to the home screen and tap Connect or the start switch. The first time you connect, the system may ask to add a VPN configuration or authorize a VPN connection. Check that the prompt is from the client you’re using before approving it. When connected, the client usually shows a connected status, and the system’s network settings or status area displays a VPN indicator. The VPN interface is the system mechanism apps use to route traffic; the actual outbound still depends on the configuration’s rules and proxy groups.

If the connection drops immediately after approval, check the logs for configuration, permission, or network interface errors. If another VPN is already connected, disconnect it and try again; some systems can’t route traffic through two VPNs at once. Also check per-app proxy settings, excluded apps, and background activity restrictions. Excluded apps may bypass the client, and the system may stop the connection if it suspends the client in the background. First test a browser in the foreground, then adjust these settings as needed.

Step 4: Test browsers and terminals separately

Check connection logs to see where requests go

Keep the client running, open an HTTPS site you use regularly in your browser, and open the client’s Connections page. Check whether the new requests appear, then review the destination domain, matched rule, and outbound route. In Rule mode, different resources on the same page may use direct or proxy connections. A page loading doesn’t prove every request used a proxy node, and a direct connection in the log isn’t necessarily a problem.

If the page loads but no new connections appear, check whether the Connections page has filters enabled or shows only active connections. You can also consult the logs from the same time. Then check that the system proxy is still on and that no browser extension or separate proxy setting is intercepting requests. Cached pages and existing connections can make testing misleading; open a new tab and make a fresh request. Checking your public IP alone isn’t enough: in Rule mode, the IP lookup itself may use a direct connection. Review the matched rule and outbound route together.

Terminals may not use the system proxy

If browsing works but a command-line request fails, test the terminal separately. Many command-line tools don’t automatically use the desktop system proxy. Use an explicit proxy option to test an HTTPS request. This example uses the local mixed port 7890; replace it with the port shown in Settings. In Windows PowerShell, use curl.exe to avoid differences caused by an alias with the same name.

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

A valid HTTP response, along with the matching request in the client, confirms that this command accessed the site through the specified proxy. The response status depends on the destination site; it won’t always be the same. If the command can’t reach the local port, first check that the core is running and the port matches. If the request reaches the client but the outbound fails, check the node, destination, and logs. Persistent terminal proxy settings depend on the tool. One successful test doesn’t mean every terminal app is routed through the proxy.

Windows UWP apps: Check loopback access separately

Consider loopback restrictions only if a regular browser works but a UWP app or another app-container program can’t use the local proxy. First confirm that the app actually uses the current proxy settings and that it’s the only app with the problem. If the client provides a UWP loopback, loopback exemption, or similar tool, open it with the required permissions. Find the affected app and enable the exemption only for that app, then fully close and restart it before testing again.

A loopback exemption lets a specific app access a local listening address. It won’t fix subscription parsing errors, unavailable nodes, or network failures in every app. Don’t select every app as a general fix, and don’t enable this for a regular browser. If the client doesn’t provide a tool, first confirm the app’s package identity, then consult Microsoft’s guidance on loopback access for Windows app containers. Avoid copying commands that don’t match the apps on your device.

Finally, test disconnecting and restoring your network

When testing is complete, turn off the system proxy before quitting the desktop client. On mobile, tap Disconnect to end the VPN connection. Open a site that normally works without the proxy and confirm your network is back to normal. If the browser still tries to use a dead local port after the client exits unexpectedly, open the system proxy settings and remove the manual proxy left by this setup. If your device previously used a work or campus proxy, restore the values you noted earlier instead of clearing settings required by your organization.

You should now be able to answer three questions: Which configuration is running? Which rule matched the request? Which outbound handled it? When troubleshooting later, check in this order: is the subscription valid → is the core running → is the app sending traffic to the client → is the outbound working? Change one setting at a time and test again. For protocol, DNS, TUN, or configuration override settings, continue to the Protocol and Core Technical Reference. To switch clients, visit the client downloads page and choose an installer for your operating system and architecture.