User Guide · Initial Setup

Clash Tutorial:
Import a Subscription and Verify Your Connection

Follow these steps: import a subscription → choose a proxy mode → connect → verify routing. This tutorial covers an initial setup that takes about 10 minutes. Have a client and a working subscription ready, then follow the steps in order. Downloading, granting permissions, and troubleshooting network issues may take longer depending on your device and network.

Before You Begin: Get a Client and Subscription Ready

Make sure the client opens and that you can access its configuration page. The client reads configurations, matches rules, and connects to proxies; installing it alone won't provide usable nodes. You'll also need a subscription URL from your service provider or a local YAML configuration containing proxy nodes, policy groups, and rules. A blank configuration or core executable alone usually isn't enough to follow these steps.

Subscription URLs often contain personal access credentials, so treat them like account information. Copy the URL using the subscription button on your provider's site; don't mistake an account login or order page URL for a subscription URL. Never post the full link in public comments or screenshots when troubleshooting. If you need to share an error, hide personal parameters in the URL and include only the error type and client name.

Before starting, quit any other proxy or VPN clients that are routing traffic. Running multiple clients at once can cause them to conflict over system proxy settings, routes, or DNS. First get everything working with one client, then explore running multiple clients if needed. If you already have a configuration, export a backup and note its name so you can restore it if something goes wrong.

Step 1: Import and Enable a Subscription

Open the Config, Subscription, or Profiles page from the sidebar or bottom navigation. Look for “Add,” “New,” or “Import from URL.” If prompted to choose a configuration type, select remote subscription or URL configuration. Use the local file option only for a YAML file already saved on your device. Give the profile a recognizable name, such as “Daily setup,” so it's easy to tell apart from other subscriptions.

Paste the full subscription URL into the address field. Check for extra spaces or line breaks at either end, then click Import, Download, or Save. Wait for the client to finish fetching it, and don't click repeatedly to create duplicate profiles. A successful import usually shows a profile card, update time, or enable button. Seeing a profile name doesn't always mean its contents downloaded; if there's an error, expand it and check the result first.

Click “Enable” or “Use” for the profile, or select its card. Some clients reload automatically; others require you to click Apply. Then open the Proxies page and check that the configuration's policy groups and nodes are listed. If the profile appears in the list but the Proxies page is still empty, make sure you've enabled the newly imported profile rather than leaving another blank profile selected.

For a local file, choose “Import from file,” select the .yaml or .yml file in the system file picker, then enable it as above. Changing a file's extension doesn't convert its contents: a web page, JSON file, or single-node share link won't become a complete configuration just by renaming it. See the YAML structure guide for an overview of configuration files.

If the import times out, first check that your network can reach the subscription host. If parsing fails, ask your provider whether it offers a Clash- or mihomo-compatible link. The response may be a login or error page; retrying won't fix an invalid format. If you need to convert a subscription, read the subscription conversion guide first. Don't submit a personal subscription URL to an unfamiliar conversion service.

Step 2: Choose Rule Mode and a Policy Group

Go to the home, overview, or Proxies page and find “Run Mode.” Choose “Rule” for your first setup. This corresponds to the configuration field mode: rule. The client checks connections against rules in order, from top to bottom, then applies the action for the first matching rule. This preserves the subscription's intended direct, proxy, and blocked routes instead of sending every connection through the same outbound.

Don't treat “Global” as a required master switch. Global mode sends all traffic that reaches the core through the global policy, bypassing normal rule-by-rule routing. Direct mode sends traffic that reaches the core straight through and can be useful for comparison. Neither mode automatically routes every app through the client. Run mode, system proxy, and TUN solve different problems; next, choose how traffic enters the client.

Once Rule mode is selected, open the Proxies page and find the group that handles general proxy traffic. It may be called Proxy, Node Selection, or something else defined by your subscription, so don't rely on one fixed name. Open the group and select a node, or choose an automatic selection group already provided by the subscription. Manual selection groups typically use type: select; automatic testing groups commonly use type: url-test.

DIRECT means a direct connection, not a proxy node. REJECT blocks connections and can't be used to browse the web. For your first test, choose a clearly identified node rather than DIRECT, REJECT, or an incompletely configured nested group. If the client offers a connectivity test, you can use it as a quick check—but success only means the test target is reachable, not that every site or app is working.

Make sure the selection indicator has moved to the intended item, then return to the overview. If your selection resets after switching profiles, check whether the new profile uses different policy group names. You don't need to learn every detail about rules, groups, and nodes yet. When you're ready to customize them, see the policy group fields and rule syntax. Avoid changing settings while learning the basics, so it's easier to identify the source of any problem.

Step 3: Connect and Route Traffic

Your configuration and outbound are ready. Now route app traffic through the client. First, check that the core is running on the overview page. If the client has a separate start button, start the core first. Opening the client window doesn't necessarily mean the proxy is working, and a tray icon alone isn't proof that it's running. If the core reports a port conflict, quit other proxy apps first instead of changing several ports at once.

Windows, macOS, and Linux: Enable the System Proxy First

Find “System Proxy,” “Set as system proxy,” or “System Proxy” on the overview or settings page. Enable it, leave the client running, and test in a browser. This typically sends connections from apps that follow system proxy settings to the client's local listening port. Support varies by desktop environment and app. On Linux in particular, check the Connections page to confirm traffic is reaching the client after enabling the switch.

For your first test, don't enable multiple traffic-capture options at once. Start with the system proxy and test in a browser. If an app doesn't follow the system proxy, consider TUN next. TUN may require service mode, administrator privileges, or system network permissions. Follow the client's prompts to install the service and grant permission; don't keep reinstalling just because the switch won't turn on. Some configurations can use system proxy and TUN together, but check your client's documentation for supported combinations.

Android and iOS: Approve the System VPN Prompt

On the mobile client's home screen, tap Connect, Start, or the power button. The first time you connect, the system will usually ask to establish a VPN connection or add a VPN configuration. Check which app is requesting access, then approve it. This VPN is the system's way of routing traffic; you don't need to install another VPN app. Return to the client and make sure its status says Running or Connected before moving on to the browser test.

If another VPN is already running on your phone, disconnect it before testing. Device management policies or work profiles may also restrict VPN access. On Android, if per-app proxying is enabled, make sure your test browser is included. On iOS, if the client still won't connect after you approve the request, check for startup errors in the client. A saved VPN configuration in system settings doesn't mean a connection is active.

After connecting, leave DNS, sniffing, and complex routing rules alone for now. First check that the basic flow works: the configuration loads, the core starts, system permissions are granted, and traffic has an entry point. For permission or traffic-routing errors, use Troubleshooting to find steps for the specific error. Keep any working settings intact, change one thing at a time, and test again.

Step 4: Verify the Result and Rule Routing

In a browser, visit a site you expect to use the proxy, such as a developer site explicitly routed through the proxy in your configuration. Once it loads, switch to the client's Connections or Active Connections page and search for the request by domain. A browser may connect to several domains to load one page. Check the main domain first, then look at image and script requests; don't use a single background request to judge the whole page.

Open the connection details and check the destination domain, matched rule, policy group, and actual outbound. If the rule points to a proxy group and the connection ends up on the node you selected, that request is being routed as expected. The group and the actual node are separate levels of information: seeing Proxy alone doesn't tell you which route was used. Automatic selection groups may also switch nodes, so check the path shown for that specific connection.

Now visit a site you expect to connect directly and check it the same way. If its rule matches DIRECT and the site loads, you've verified both proxy and direct routing. Checking your public IP can be useful, but the IP lookup site may itself be routed differently by your rules. A single IP page can't prove that all traffic is using the proxy, and it doesn't replace checking the connection records.

If a page won't load, break the problem into three parts. First, is the connection reaching the core? If you can't find the request on the Connections page, check the system proxy, mobile connection status, and per-app routing scope. Second, is it being routed correctly? If the request is there but uses the wrong policy, check Rule mode and the enabled profile. Third, is the outbound working? If the rule is correct but the connection fails, try another available node and check the logs for DNS, timeout, or handshake errors.

Existing long-lived connections may not move to a new node immediately, and browsers may reuse old connections. After switching policies, reload the page. For a clearer comparison, close the relevant active connections in the client before sending the request again. Closing all connections can interrupt downloads, calls, or file transfers, so do this only when nothing important is in progress.

After verifying your setup, remember three things: which profile is active, which node or group the general proxy group uses, and which traffic-routing method is working. If something breaks later, start from these known-good settings and troubleshoot one layer at a time instead of resetting your subscription, DNS, and mode all at once. If browsing works but a specific app doesn't, see Troubleshooting. To change how a domain is routed, see the custom rules reference.

After Connecting: Startup, Updates, and Shutdown

Once the basic test works, enable “Start on boot” or “Launch at login” in the client's settings if you need it. On desktop, “Launch app,” “Connect on startup,” and “Set system proxy automatically” may be separate options. Enabling one doesn't enable the others. Set only what you need, then sign out and back in or restart your device. Check that the profile, core, and traffic-routing method all come back, then test a webpage again.

Mobile background operation works differently from desktop startup. If Android frequently stops the app, check battery optimization, background activity, and the device's own auto-start settings. These options vary by device; don't grant permissions unrelated to network access just to keep the app running. On iOS, on-demand connection support depends on the client and system capabilities. Use the options available in the app rather than following desktop instructions.

To update a subscription, return to the Config page and refresh or update the active subscription. When it's done, make sure the same profile is still enabled. If the client supports automatic updates, follow your provider's recommended interval; there's no need to set it too frequently. Remote updates may overwrite edits made directly to the original file. If you need to keep custom changes, learn how your client handles overrides, then read the configuration fields reference.

Finally, test how to disconnect. Before quitting a desktop client, turn off the system proxy or use the client's normal exit option, so your system won't keep sending traffic to a local port that is no longer listening. If your browser can't connect afterward, check whether system proxy settings are still enabled. On mobile, disconnect in the client and make sure the system VPN status updates too. Knowing how to connect and disconnect makes it easier to keep track of the current state.