GUIDE First-Time Setup
Clash Setup Guide
Import a subscription, choose a proxy mode, and check which rule handles your traffic.
Import a subscription and activate the configuration
First, check whether you have a subscription URL or a local YAML file. The client fetches a subscription URL, which you can usually update later from the Profiles page. Importing a local file adds a copy that may not sync when the original changes. Choose either method. If you already have a working configuration, give the new import a distinct name and keep the old one for now so you can switch back if anything goes wrong. Subscription URLs may contain access credentials; don't share them in public logs, screenshots, or shared documents.
Add a source on the Profiles page
Open the client's Profiles or Subscriptions page and choose Add, Import, or the plus button. For a URL, select Import from URL, paste the full address, and confirm. Wait for loading to finish, then check that the new configuration appears in the list. If the client reports an unsupported format, make sure you have a Clash subscription for that client, not an account management webpage URL. If it times out, check your device's internet connection and confirm the URL is still valid; you don't need to enable the system proxy first.
For a file, choose Import from file and locate the actual YAML file in the system file picker. If you get a parsing error with a line number, check that line and the one above it: inconsistent indentation or a missing colon on the previous item can cause an error to be reported on the next line. Try importing the original copy first. If you need to edit it, make one change at a time in a backup. Don't rename a downloaded login page with a YAML extension and try to import it.
Confirm the configuration is active
A successful import only means the configuration was added. Return to the list, select the entry, and choose Activate or Apply from its menu. Check that the active indicator moves to the new entry. If the client asks you to reload the configuration, wait for the reload to finish before opening the Proxies page. A configuration with proxy groups should show the groups defined by the new configuration. If you still see the old group names, check the selected profile and loading status before importing again.
Before continuing: Check that the configuration name is correct and that it loaded without parsing errors. For the YAML top-level structure, see Configuration Field Reference.
Choose a proxy mode and outbound
For your first connection, choose Rule mode to check that traffic follows the expected rules. On the Proxies or Settings page, find Mode and select Rule or Rule, then confirm the selected option is highlighted. Mode controls how the core routes traffic; it does not send system app requests to the core. It’s normal if your browser behaves the same for now—you’ll configure the traffic entry point next.
In a mihomo-compatible YAML file, this setting corresponds to the top-level mode key. The example below shows only the field, not a complete configuration. For your first setup, change the mode in the client UI: runtime settings may override the value in the file. Use the mode shown in the UI as the source of truth.
mode: rule
Choose an outbound in the rule's proxy group
Choose a test destination whose expected route you know, then check the matching rule in your configuration. If the domain should match a manual proxy group, open that group on the Proxies page, select an available node, and confirm it is marked as selected. For an automatic or fallback group, leave its behavior unchanged and check the actual outbound in the connection details later. Don't infer the route from a group's name alone: switching a group called “Manual” won't affect a destination unless its rule uses that group.
Global mode can help you temporarily check whether an outbound works. If you use it for testing, check what the global selection points to. A successful global-mode test doesn't prove that Rule mode matched the intended rule. Direct mode can help test basic connectivity, but it doesn't prove the system bypassed the core: requests may still pass through the core and be forwarded directly. Switch back to Rule mode after testing so temporary settings don't affect the next checks.
Before continuing: Note the current mode, the expected proxy group, and the selected outbound. If you're unsure which rule matches first, see Rule Syntax and Matching Order.
Enable the system proxy or mobile VPN
For your first test, enable only one way of routing traffic so you can tell where requests are going. Check that the client shows the core as running. Some clients start the core when opened; others require you to select Start or Connect. If the client reports a port conflict, an unloaded configuration, or a core startup failure, resolve that first. Otherwise, even with system routing enabled, no local process may be listening for the request.
Desktop: Enable the system proxy
Find System Proxy on the client's home page, in Settings, or in the tray menu. Turn it on, then check the operating system's network or proxy settings. For a manual local proxy, make sure the loopback address and port match the client's listener. For example, if the configuration uses mixed-port: 7890 and the client hasn't overridden it, the local proxy address is 127.0.0.1:7890. Don't enter a remote node's port here or assume the example port is the default for every client.
For your first test, use a browser that respects the system proxy settings. A browser with its own proxy configuration—or an app that ignores the system proxy—may not follow the system toggle. If the client also offers a TUN switch, don't enable it alongside the system proxy. Consider TUN only if you've confirmed the target app doesn't use the current routing method. On a managed device, leave the existing network settings intact and follow your organization's policies.
Mobile: Approve the system VPN request
Tap Start or Connect on the client's home page. When prompted for the first time, approve the VPN request from the client, then return to the app and check that it shows as connected. If you dismiss the authorization prompt, tap Connect again to trigger it. If another VPN is already running, check which connection is active; switching may interrupt it. Don't remove a VPN managed by your organization or device administrator.
Before continuing: Leave your chosen traffic-routing method enabled. To pause testing, first turn off the system proxy enabled by the desktop client, then stop the core. On mobile, disconnect in the client and check the system VPN status.
Verify the proxy connection in the logs
Use a new request to check three things: whether it reached the core, matched the expected rule, and completed successfully through the selected outbound. Open the client's Connections page, or its Logs page if it shows routing details. Note the time, then visit a reachable test destination with a known expected rule in your browser. A page loading is only the first check—a direct connection can load it too.
Check the destination, rule, and outbound
Find the entry in the connection log by destination domain and request time. Don't mistake an image or other resource from the same page for the main page request. Open the details and compare the matched rule, proxy group, and actual outbound. If the configuration expects the destination to connect directly, DIRECT is the expected result. If it should use a proxy group, check that the actual outbound is the node currently selected in that group. For an automatic group, use the node shown in this connection's details, not just the group name.
If your configuration has both direct and proxy rules, test another destination that should take the opposite route. After changing the mode or proxy group, make a new connection before checking the result. Your browser may load a page from cache or reuse an existing connection. If needed, try a destination you haven't visited before, or restart the browser. Don't use an old connection log to judge a new setting.
Troubleshoot by failure point; change one thing at a time
If you can't find the request, check the time and domain. Watch the connection list while making the request in case it disappears too quickly to remain visible. If it's still missing, check whether the system proxy or VPN is active and whether the browser has its own proxy settings. If there's a record but the rule is wrong, check the current mode, rule order, and fallback rule—not the node first. If the rule is correct but the request times out, check the log for the first error, such as a DNS resolution failure or connection timeout. Fix only the setting related to that error, then test with a new request.
First-time setup complete: The test destination loads, and the connection log shows the expected route. If you still can't identify the problem, follow the Troubleshooting FAQ. If the log reports a DNS resolution failure, check the DNS Configuration Fields.