Before You Start

Before you begin, make sure the client is installed and opens to its main window. Have a subscription URL you’re authorized to use, or a complete Clash YAML configuration file. The client reads the configuration, runs the core, and manages traffic routing; it does not provide a proxy service by itself. Without a configuration, installing the app usually isn’t enough to connect.

Temporarily quit other proxy clients and note whether you have a browser proxy extension, system VPN, or manual proxy enabled. For your first setup, use just one traffic-routing method. Otherwise, your browser may still use a different configuration, making the client’s status inconsistent with what you see online. On a work, school, or managed device, follow your organization’s device and network policies; don’t change managed proxy settings.

A subscription URL may contain account-identifying information, so treat it like a credential. Don’t post the full URL in public forums, screenshots, or online conversion tools. This guide covers client setup and doesn’t ask you to share subscription details. If you run into a format issue, first look for an export option explicitly labeled Clash or mihomo in your provider’s account portal.

01 / Import a Subscription and Activate the Profile

Open Profiles in the left sidebar and find the option to add, import, or create a remote profile. Paste the subscription URL into the URL field. If you can enter a name, choose something easy to recognize, such as “Everyday.” The name is for local organization only; it doesn’t replace the URL or determine which proxy is used. Check for spaces, line breaks, or punctuation copied from a chat app at either end of the URL, then import it.

Wait for the download to finish; don’t click repeatedly. The profile list should show a new entry, usually with its name, source, or last-updated time. Some versions save a remote profile first and download its contents separately. If there’s an update button, use it once and check for errors. Seeing a profile in the list doesn’t mean the core is using it yet—you still need to activate it.

Select the profile you just imported, then choose Apply, Enable, or Set as current profile. Confirm the current-profile indicator moves to that entry, then open Proxies and check that the profile’s proxy groups appear. If the Proxies page is still empty, return to Profiles and check that you selected the right entry. Then look in the logs for parsing or profile-loading errors. Repeatedly toggling the system proxy won’t fix a configuration error; these are separate steps.

Import a Local YAML File

If you already have a complete configuration, use the local file import option to select a file with the .yaml or .yml extension, then activate it as you would a subscription. Changing a file’s extension to YAML doesn’t convert its contents: a webpage, QR code screenshot, or plain list of proxy nodes isn’t a complete configuration. You don’t need to edit the file by hand for your first setup. Start with a compatible version provided by your subscription service.

After importing a local file, the client may save a copy. Changes to the original file may not sync with the imported profile, so check how your client handles editing or reimporting. Remote subscriptions are refreshed with the update action; the two sources are managed differently. For more on the distinction between a profile entry and the file currently in use, see Profiles and configuration concepts in the glossary.

If Import Fails, Troubleshoot This Step First

If the download fails, check whether the URL has expired and whether your network can reach the subscription service. If parsing fails, confirm the response is actually Clash YAML. An account login page, service error page, or Base64-encoded list of proxy nodes isn’t a complete configuration just because it came from a URL. Don’t submit unverified content to random online conversion tools. If conversion is necessary, ask your provider which methods it supports.

After your first successful import, use manual updates until you’re comfortable with the setup. If you want scheduled updates, set an appropriate interval for the remote profile and check afterward that the active profile and proxy group selection still match your expectations. At this point, you should have an activatable profile with visible proxy groups. Next, choose how to route requests.

02 / Choose a Proxy Mode and Group

On the Dashboard or Proxies page, set the operating mode to Rule for your first setup. In Rule mode, requests are matched from top to bottom against the loaded configuration’s rules, then sent to the specified direct action, proxy, or proxy group. Rule mode doesn’t send every request through the same proxy or fill in missing rules automatically. The loaded configuration determines what happens.

If the client offers Global and Direct modes, know what each does. Global mode typically sends requests to a single global proxy group, which can help you check whether routing rules affect the result—but you still need to choose a working proxy. Direct mode is mainly for restoring direct access or testing for comparison. Try other modes after you’ve connected successfully. Changing the mode, profile, and proxy all at once makes it harder to isolate a problem.

Choose a Proxy Group

Open Proxies and expand a selectable group provided by the active profile. Group names are set by the configuration author: they may not be called PROXY or match the names in screenshots. Find the main group for everyday traffic and select an available proxy from your subscription. If the profile includes an automatic selection group, you can direct the main group to it instead. Automatic switching depends on the group type and settings, not whether its name includes “Auto.”

Keep the two roles separate: the operating mode determines whether rules are used; the proxy group determines which proxy handles a request matched by a rule. Selecting a proxy won’t help if the main group still points to DIRECT. Conversely, a correctly selected group won’t route a test domain through that proxy if an earlier rule sends it to DIRECT. Don’t edit the YAML yet. First check the group’s selected option and keep the profile’s existing routing logic.

If no options appear in a proxy group, go back to the profile setup instead of continuing. The subscription may be incomplete, a proxy provider may not have updated, or the group referenced by the rules may not match an existing group. For field structure and group references, see the YAML guide. Once this step is complete, keep Rule mode and a clearly selected proxy, then move on to system proxy settings.

03 / Start the Core and Enable the System Proxy

Return to the Dashboard or Settings and confirm the core is running. Some versions start it automatically after applying a profile; others have a separate start control. If the logs keep reporting configuration errors, fix the profile first. If a port is already in use, check for another instance or proxy app that’s still running. An open app window doesn’t mean the core is listening on a local port.

Keep the client’s existing listener ports for your first setup. Don’t change them to match a tutorial. The logs may show a listener message like the example below; the example port is common, but isn’t required for every installation. Use the active configuration and your local logs as the source of truth.

level=info msg="Mixed(http+socks) proxy listening at: 127.0.0.1:7890"

Once the core is running, turn on the system proxy. This usually points your operating system’s proxy address to the client’s local listener so apps that follow system proxy settings can use it. If the system asks for permission, confirm the prompt comes from your client and follow the system instructions. Keep the client running after enabling the proxy; don’t immediately close it or stop its background process.

Test Your First Connection in a Browser

Open a browser that follows system proxy settings and visit a new page. Temporarily disable any browser extensions with their own proxy settings so they don’t override the system settings. Some browsers have separate network proxy options, and some command-line tools require their own proxy parameters. If they don’t follow the system proxy, that alone doesn’t mean the client is broken. For your first test, use a browser with the simplest setup.

On Windows, check manual proxy status in Settings under Network & Internet > Proxy. On macOS, check the proxy settings for your current network service. On Linux, check the proxy settings for your desktop environment. Support varies by distribution and desktop session. If the client says it couldn’t apply the settings, verify the actual address and port in system settings instead of relying on the toggle’s appearance.

Don’t Enable TUN at the Same Time

This guide uses the system proxy to test one observable browser request; you don’t need to enable TUN for your first setup. TUN handles more traffic through a virtual network interface and requires additional permissions and routing and DNS setup. It isn’t another name for the system proxy or a fix for every connection problem. If you need to route apps that don’t follow system proxy settings, read the glossary entry on TUN and system proxies, then configure the required service or permissions for your client.

On phones, this step usually means tapping Connect and allowing the system to establish a VPN connection. The system may show a VPN status indicator, but that only confirms the routing mechanism has started; it doesn’t prove the subscription’s proxy is working. Whatever the platform, verify the setup with an actual request and the client’s connection records.

04 / Verify Rules and Connections

Keep the client running, then revisit a familiar HTTPS page that normally loads reliably. Open the client’s Connections page and check for a record matching the domain or destination as the page loads. If the client shows rule and routing details, expand the record to see which rule matched and which proxy group was used. A page loading is only the first check; the connection path shows whether traffic was routed as expected.

Compare two destinations with clear expected routes: one that should go direct under the current profile and another that should use a proxy. Check the rules or connection details before drawing conclusions; page content or apparent location doesn’t tell you which route it took. If both requests show DIRECT, check the operating mode and matched rules. If the selected proxy group is shown but the page still fails, check whether that proxy and the destination service are available.

No Connection Records? Check the Routing Path

First, make sure the browser isn’t reusing an existing long-lived connection. Close the test tab and open it again. If the record still doesn’t appear, check in system settings that the proxy was actually applied and make sure the browser isn’t using its own proxy configuration. Some clients only show active connections, so short requests may disappear quickly; check the logs as well. Don’t change rules or DNS just to keep a record visible.

If a page won’t load, check each step in order: profile activated → core started → local port listening → system proxy applied → proxy group selected. Change one setting at a time, then repeat the same page request. This helps distinguish a local routing issue from a proxy connection issue, and shows which change affected the result.

Use Logs to Find the Failing Step

Open Logs and focus on errors or warnings from around the time of your test. A configuration parsing error means you should return to the import step; a listener error points to a port conflict; a connection timeout needs to be checked against the destination and selected proxy; a name resolution error calls for a closer look at DNS routing. Before sharing logs, remove subscription URLs, account details, and other sensitive information. See the YAML configuration reference for DNS fields and rule syntax; you don’t need to rewrite them for your first test.

If you check your public IP on an external site, remember it only shows the route for that specific request—not the route used by every app. Rule mode is designed to send different destinations through different paths. A reliable setup means the profile loads, the test request appears in the client, the matched rule is expected, and the destination page opens successfully.

Disconnect and Start Again

When you’re done testing, turn off the system proxy before quitting the client. If you used TUN, turn off its traffic-routing switch too and stop its service using the client’s instructions. Force-quitting the app may leave system proxy settings pointing to a local port. If your browser can’t connect afterward, restore the system proxy settings instead of reinstalling the app.

The next time you start the client, confirm the expected profile is active, the remote subscription updates successfully, and the mode, proxy group, and system proxy settings are correct. Don’t enable startup launch, automatic routing, and complex overrides all at once. Keep the settings you’ve already tested. When you’re ready to add custom rules, switch profiles, or use overrides, make changes in the YAML guide one at a time and repeat the verification steps after each change.

Import a Clash Subscription and Configure Proxy Settings