Before You Begin: Check Your Configuration Source and Network
First, make sure websites that normally work still load when the client is off, and complete any public Wi-Fi sign-in. This helps distinguish a local network issue from a proxy setup problem. For your first setup, pause other proxy clients and VPNs, and keep this guide open. If changing routes over a remote desktop connection, make sure you can restore the connection before enabling traffic capture.
Get a Clash- or mihomo-compatible subscription URL from a trusted source, or a YAML configuration file provided by your service. The client reads the configuration and handles connections; it does not provide a working proxy service by itself. A list of node addresses, a web account URL, or a subscription in another format may not import directly. Check the provider's instructions for the supported format, and never enter your account password in the configuration name field.
Subscription links often contain credentials that identify your account, so protect them like passwords. When copying, check for leading or trailing spaces, line breaks, or text added by a chat app. Don’t paste the link into an unknown online converter or show the full URL in a public screenshot. Once ready, open the client's main window and go to configuration management.
Step 1: Import and Enable a Subscription
Open “Subscriptions,” “Configurations,” or “Profiles,” then look for “New,” “Add,” “Import,” or a plus button. Choose URL import and paste the full subscription URL into the address field. You can enter a descriptive name to identify the source. Check the URL, then click Import or Save and wait for the client to download and parse it. Your current network must be able to reach the subscription server.
For a local file, choose “Import from file” and select the .yaml or .yml file. Don’t just rename a downloaded webpage to YAML; the right extension doesn’t guarantee valid content. Check that the file source identifies the compatible core. If the client reports a parsing error, note the line number and field name, then ask the configuration provider for help. Don’t keep deleting fields to force it to load.
After a successful import, the configuration list usually shows a new entry with its name, update time, or source. Some clients enable the new entry automatically; others require you to click its card or choose “Use” or “Activate” from a menu. Make sure the newly imported configuration is selected. A “Download successful” message alone doesn’t mean the core is using that configuration.
Next, open the Proxy page and check for proxy groups and their nodes. Group names are set by the configuration author and may include “Node Selection,” “Proxy,” or other labels; they don’t need to match this guide exactly. If the page is still empty, return to the configuration page, check that the right entry is enabled, and look for a load error. Fix the configuration first; don’t switch to global mode or repeatedly toggle TUN yet.
Updating a subscription and enabling a configuration are separate actions. When you click Update, the client fetches the remote content again. If the provider changes the nodes, your previous manual selection may remain. After updating, return to the proxy group and confirm that your selection is still valid. Direct edits to a remote configuration may be overwritten on the next update. Save custom rules for later, using the client's supported override method once the basic connection works.
You’re ready to move on when the configuration is enabled and proxy groups are available on the Proxy page. Once both are in place, choose a mode. For an explanation of subscriptions, configuration files, and proxy groups, see the glossary. You don’t need to understand every YAML field to make your first connection.
Step 2: Choose a Rule Mode and Node
Look for a mode selector on the Overview, Proxy, or Settings page. For your first setup, choose “Rule” or “Rules.” The core uses the configuration's rules to decide whether connections go direct, through a proxy, or are blocked. Actual behavior depends on the configuration; the client doesn’t automatically know which route each website should use. If no rule matches, the configuration's final rule applies.
After switching to rule mode, open the main proxy group in your configuration. If it lists individual nodes, start with one you know works for the service you’re using. If you see a group such as “Auto Select” or “Failover,” you can choose that instead and let the configuration's testing and switching logic pick the route. A region in a group name doesn’t guarantee the exit location—verify it in the final step.
If the client offers a latency or connection test, run it once as an initial check. A result means the test target responded under those conditions; a timeout means you’ll need to check the node or network further. The reported latency isn’t download speed and doesn’t prove every website will load. Some services restrict certain exit IPs or protocols, so test the actual site even if the node test succeeds.
Global mode sends connections that have reached the core through the global policy. It’s useful for a quick comparison to check whether a problem is related to routing rules. Direct mode typically sends connections that reach the core straight to their destinations. These modes describe how the core handles connections, not how it captures them. Without the system proxy or another capture method, apps may bypass the core even in global mode.
If you use global mode for troubleshooting, make sure the global policy selects a specific node, not DIRECT. Switch back to rule mode when you’re done so services that should connect directly aren’t routed through a proxy. For your first setup, avoid reordering rules or changing DNS. Test the imported configuration with its default behavior first to keep variables to a minimum.
You’re ready to move on when the mode is set to Rule and the active proxy group has a selected node or a working automatic selection group. The client can now handle connections, but browser traffic may not have reached the core yet. Next, enable traffic capture rather than stopping at the Proxy page.
Step 3: Enable the System Proxy or TUN
Return to the Overview page and make sure the core is running. If the client has a separate Start, Connect, or core toggle, start it before changing traffic capture settings. If parsing failed and the core isn’t running, enabling the system proxy may point your browser to a local port with nothing listening, making every page fail to load. Confirm the core is running before enabling the proxy.
Desktop: Test in a Browser with the System Proxy
In the Windows or macOS desktop client, find and enable the System Proxy toggle. It usually points the operating system's proxy settings to the local core, so browsers and apps that follow those settings use it. Open a new browser tab after enabling it, or restart apps that were already open so their new connections pick up the setting. Existing long-lived connections may not switch immediately.
Apps with their own proxy settings may override the system settings, while some apps ignore them altogether. That doesn’t necessarily mean the node is broken. Linux desktop support for system proxies varies, and some clients only configure the current desktop session; terminal apps may need separate setup. First establish a working baseline with a browser that follows the system proxy, then troubleshoot other apps.
Mobile: Approve the System VPN Connection
In the Android or iOS client, select a configuration and node, then tap Connect. The system may ask to add a VPN configuration or approve a VPN connection. Confirm the request comes from your client, then follow the prompts; some devices require you to unlock the screen or enter your device passcode. Once connected, VPN status usually appears in system settings or the status area, though the icon varies by OS version.
The VPN interface is the system mechanism the client uses to capture device traffic. It doesn’t mean traffic bypasses the configuration's routing rules. After connecting, verify that websites load and the expected rules are matched. If another VPN is running, disconnect it before testing. Work-device policies may restrict VPN configurations; if the system denies the request, check your permissions rather than repeatedly importing the same subscription.
TUN: Enable It Only If You Need to Capture More Traffic
If your browser works but an app has no connection records, consider TUN mode. Look for “TUN,” “Virtual Network Interface,” or an enhanced traffic capture option, then follow the client's prompts to install a service, grant administrator permissions, or approve a network extension. TUN can capture eligible traffic at the routing layer, but what it captures still depends on routes, exclusions, and DNS settings. It doesn’t guarantee that every connection will use the proxy.
For your initial test, turn off the system proxy and test TUN on its own so you can tell which capture method is working. This is a troubleshooting approach, not a rule that every client must keep them separate. If enabling TUN affects your local network, printer, or another VPN, turn it off to restore the previous state. For platform-specific details on permissions, virtual network interfaces, and routing conflicts, see the all-platform installation and setup guide.
You’re ready to move on when the core is running, your chosen traffic capture method is enabled, and no permission prompts are waiting. “Connected” in the client only confirms a running state; it doesn’t guarantee the target website will load. Keep the current settings and move on to the final test.
Step 4: Verify Access and Rule Matches
First, open a website that normally works over a direct connection to confirm your basic network is still working. Then open a new tab and visit a site that your configuration should route through a proxy. Make sure the page fully loads, not just its title. Don’t rely on a cached page alone; refresh or open a new browser window if needed, and check whether the client shows a new connection.
Open the client's Connections or live log page and filter by the domain you just visited. Connection details often show the destination domain or IP, matched rule, proxy group, and final node. The fields vary by client; what matters is confirming that traffic reached the core and followed the expected policy chain. A DIRECT result isn’t necessarily an error—first check whether that destination should connect directly.
If the connection details show a proxy policy, you can also check the exit IP using a trusted IP lookup site. The result reflects the exit used for that request; it doesn’t mean every app on your device uses the same exit or prove that DNS is handled as expected. Some configurations route lookup sites directly, so check the result alongside the domain's rule record rather than relying on a region label alone.
Something Not Working? Trace the Connection Path
If the client shows no connection for the target, first check that the system proxy or TUN is actually enabled. Then check whether the app has its own proxy settings or is reusing an existing connection. Close and reopen the app, then try again. If no traffic is reaching the core, changing nodes won’t help; confirm the capture path first.
If a connection appears but uses an unexpected policy, check that the right configuration is selected and that the proxy group points to the intended node. Rules are matched in order, so an earlier rule can take precedence over a later one. You can briefly switch to global mode for comparison: if the site works in global mode but not in rule mode, check the rules or their DNS behavior. That alone doesn’t identify the specific rule at fault.
If the connection uses the expected node but times out, try another known-working node, then check whether your service has expired or usage restrictions apply. If domain resolution fails, keep the error details and first confirm that your network and the configuration's DNS service are reachable. Don’t change nodes, modify DNS, reinstall the client, and enable TUN all at once. Change one thing at a time and repeat the same test so you can tell what helped.
When sharing troubleshooting details, note the client name, operating system, traffic capture method, error, and steps that triggered it. Before sharing a screenshot, hide the full subscription URL, node passwords, account details, and local control interface credentials. Logs may also contain visited domains and device paths, so review them before sharing. For unfamiliar terms, see the glossary for DNS, fake-ip, proxy groups, and TUN.
Save Your Settings and Disconnect
Your initial setup is complete when both direct and proxied sites load as expected and connection records match your expectations. Note the active configuration, mode, and traffic capture method so you can return to a working setup after future updates or changes. For automatic subscription updates, launch at startup, or more detailed app routing, see the all-platform guide next. You don’t need to enable everything for your first connection.
When you’re done, turn off the system proxy or disconnect the VPN or TUN in the client before exiting. A normal shutdown usually restores the related settings, but the system proxy may remain if the client closes unexpectedly. If your browser can’t connect after you exit, first check whether the manual proxy in system network settings still points to your local machine. If you used TUN, check that the client service and virtual network interface have stopped as expected. Restore your normal network before deciding whether to reconnect.